opencode-thrum-pro 0.1.0

package/assets/skills/thrum/resources/IDENTITY.md

@@ -0,0 +1,49 @@
+# Agent Identity
+
+## Registration
+
+Every agent must register before sending or receiving messages.
+
+```bash
+thrum quickstart --name <agent-name> --role <role> --module <module> --intent "<description>"
+```
+
+This registers the agent, starts a session, and sets the work intent.
+
+## Identity Components
+
+- **Name** — Human-readable identifier (auto-generated or via `--name`)
+- **Role** — Function category: `implementer`, `planner`, `reviewer`, `tester`,
+  `coordinator`
+- **Module** — Work area: `auth`, `website`, `api`, `testing`, etc.
+- **Agent ID** — Format: `<name>:<role>:<module>` (e.g.,
+  `claude_impl:implementer:auth`)
+
+## Identity Storage
+
+Identities persist in `.thrum/identities/<name>.json`. Registration is
+idempotent — re-registering with the same name updates the existing identity.
+
+## Multi-Worktree Identity
+
+See [WORKTREES.md](WORKTREES.md) for multi-worktree identity setup.
+
+## Checking Identity
+
+```bash
+thrum whoami          # Current identity
+thrum overview        # Identity + session + team + inbox + sync
+thrum prime           # Full context including identity
+```
+
+## Session Lifecycle
+
+```bash
+thrum session start                        # Begin session
+thrum session set-intent "new intent"      # Update intent
+thrum session heartbeat                    # Keep alive
+thrum session end                          # End session (do this when done)
+```
+
+Sessions make your agent visible in `thrum team`. Forgetting to end sessions
+creates stale entries.

package/assets/skills/thrum/resources/LISTENER_PATTERN.md

@@ -0,0 +1,64 @@
+# Listener Pattern: Background Message Monitoring
+
+> **Prefer tmux-managed sessions when tmux is available.** They deliver messages
+> at zero token cost with no background listener needed. See
+> [TMUX_SESSIONS.md](TMUX_SESSIONS.md). Use the listener pattern below when tmux
+> is not available or not practical for your setup.
+
+The message-listener is a background sub-agent that blocks on `thrum wait` and
+returns when messages arrive. A PID file (`.thrum/var/<agent_id>-listener.pid`)
+prevents duplicate listeners — spawning when one is already running is safe.
+
+## Quick Start
+
+```text
+Task(
+  subagent_type="message-listener",
+  model="sonnet",  # low effort
+  prompt="Listen for Thrum messages.\nSTEP_1: /path/to/repo/scripts/thrum-startup.sh --listener-heartbeat\nSTEP_2: thrum wait --timeout 8m --after -15s --agent-name <agent_id>"
+)
+```
+
+Replace `/path/to/repo` with the actual repo path and `<agent_id>` with your
+agent name. `thrum prime` outputs a ready-to-use spawn instruction with both
+pre-filled.
+
+## How It Works
+
+1. **Spawn** — Launch as background Task (`background: true` in frontmatter)
+2. **PID file** — `thrum wait --agent-name` writes a PID file on start, updates
+   it each cycle, and removes it on exit (or signal). All spawn paths check this
+   file with `kill -0` before spawning.
+3. **Block** — `thrum wait --timeout 8m` blocks until message or timeout
+4. **Return or loop** — Message received → stop. Timeout → back to step 2.
+
+The listener loops internally (up to ~30 cycles of 8 min = ~4 hours max).
+
+## Wait Command Flags
+
+| Flag              | Purpose                                                 |
+| ----------------- | ------------------------------------------------------- |
+| `--timeout 8m`    | Block up to 8 min per cycle (under Bash 600s limit)     |
+| `--after -15s`    | Include messages sent up to 15s ago (covers re-arm gap) |
+| `--agent-name ID` | Write PID file for spawn coordination                   |
+
+## Cron Watchdog (Recommended)
+
+Automatically respawn the listener if it dies or is lost after compaction.
+
+```text
+CronCreate(
+  cron="*/30 * * * *",
+  prompt="Check the listener PID file at .thrum/var/<agent_id>-listener.pid.\nIf the file does not exist, or if kill -0 <pid> fails (process not running),\nspawn a new listener:\n\nAgent(subagent_type=\"message-listener\", model=\"sonnet\", prompt=\"Listen for Thrum messages.\\nSTEP_1: /path/to/repo/scripts/thrum-startup.sh --listener-heartbeat\\nSTEP_2: thrum wait --timeout 8m --after -15s --agent-name <agent_id>\")"
+)
+```
+
+Spawn the initial listener on session start, then create the cron watchdog.
+
+## Key Rules
+
+- **Spawn freely** — PID file prevents duplicates
+- **Return immediately** when messages arrive (don't wait for more)
+- **Read-only** — the listener never sends messages
+- **Cost-efficient** — runs on sonnet-low, blocks instead of polling
+- Listener uses CLI only (`Bash` tool), not MCP tools

package/assets/skills/thrum/resources/MESSAGING.md

@@ -0,0 +1,163 @@
+# Messaging Protocol
+
+## Message Lifecycle
+
+1. **Send** — `thrum send --to @name --body-file msg.md` (direct; see
+   §Shell-Safe below for heredoc form)
+2. **Deliver** — Daemon writes to recipient's inbox (JSONL in
+   `.git/thrum-sync/`)
+3. **Receive** — `thrum inbox` or `thrum wait` (blocking)
+4. **Verify sent state** — `thrum sent` or `thrum message get <msg-id>`
+5. **Read** — Auto-marked read when displayed via `thrum inbox`; use
+   `thrum inbox --unread` to peek without marking. Explicit:
+   `thrum message read --all`
+6. **Search — do not page through the inbox to find old messages.** The
+   default page is 10, newest-first, so stale unread sorts LAST exactly when
+   it has waited longest. Use `thrum message search "<term>"` (full-text,
+   positional query, no `--limit`) or `thrum inbox -q "<term>"` (same search
+   scoped to your inbox). `thrum message reindex` rebuilds the FTS index if
+   search looks wrong.
+7. **Reply** — `thrum reply <msg-id> --body-file reply.md` (see Addressing for
+   the no-`--to` rule)
+
+## Addressing
+
+| Target              | Routing                                                       | When to use                          |
+| ------------------- | ------------------------------------------------------------- | ------------------------------------ |
+| `--to @lead_agent`  | **Direct** — routes to the named agent                        | Default for all task messages        |
+| `--to @coordinator` | **Role fanout** — ALL agents with that role (warning emitted) | Only when you want every coordinator |
+| `--to @everyone`    | **Broadcast** — all registered agents                         | Critical alerts                      |
+
+**Critical:** `@coordinator` is a role, not an agent name. Sending
+`--to @coordinator` fans out to every agent registered with that role. Use
+`thrum team` to find agent names, then send `--to @<name>` for direct messages.
+
+- **Reply:** `thrum reply <msg-id>` — same audience as original; takes **no
+  `--to`** (recipient derived from the message)
+- **Unknown recipient** — hard error; verify names with `thrum team`
+
+## Shell-Safe Message Bodies (backticks, `$(...)`, `$VAR`, quotes)
+
+**The trap:** a double-quoted body is processed by your shell _before_ thrum
+runs. Backticks and `$(...)` are command-substituted, `$VAR` is expanded, and
+the original text never reaches thrum — it cannot detect or repair the
+corruption. Single-quoting is only a stopgap — it breaks on apostrophes in
+prose.
+
+**The safe default:** read the body from stdin or a file instead of passing it
+as a quoted argument. A **quoted** heredoc (`<<'EOF'` — note the quotes around
+`EOF`) disables _all_ shell interpretation, so backticks, `$`, apostrophes, and
+quotes all pass through literally. Available on `send`, `reply`, and
+`message edit`:
+
+```bash
+# Preferred: quoted heredoc via --stdin (safe for backticks, $, apostrophes)
+thrum send --to @agent_name --stdin <<'EOF'
+Run `make build` then check $(git rev-parse HEAD). It's done.
+EOF
+
+# Reply the same way (no --to — recipient comes from the parent message)
+thrum reply msg_01HXE... --stdin <<'EOF'
+Done — see `internal/foo.go`. Cost was $(estimate).
+EOF
+
+# From a file
+thrum send --to @agent_name --body-file ./body.md
+
+# '-' as the body argument is a --stdin alias (good for pipes)
+some-generator | thrum send --to @agent_name -
+```
+
+Rules:
+
+- `--stdin` and `--body-file` are mutually exclusive, and neither may be
+  combined with a positional body (the command errors on ambiguity).
+- A single trailing newline (the one the heredoc adds) is stripped; additional
+  blank lines are preserved.
+- All bodies must be supplied via `--stdin` (or `-`), or `--body-file` —
+  positional body arguments are refused to prevent silent shell substitution.
+
+## Permission-Prompt Routing
+
+Runtime permission prompts (e.g. "Allow this tool?") route to recipients listed
+in `permission_supervisors` in `.thrum/config.json`. **The array is
+authoritative** — the daemon sends the nudge to each entry in order, with no
+auto-detect or broadcast fallback behind it.
+
+```jsonc
+{
+  "permission_supervisors": [
+    "coordinator", // role → fans out to every active coordinator
+    "@your_coordinator", // specific agent (name-based)
+    "@user:jane-doe", // user → auto-bridges to Telegram if configured
+  ],
+}
+```
+
+**Invariant:** the list must include at least one coordinator-role recipient —
+either the bare role `"coordinator"` or an `@coordinator_*` agent name. When
+absent or empty, the resolver defaults to `["coordinator"]`. If the list is
+non-empty but has no coordinator entry, the daemon warns at start and continues
+(prompts may still go undelivered if the listed agents are offline).
+
+## Threading
+
+Replies auto-create implicit threads. When you `thrum reply`, the daemon assigns
+a shared `thread_id` to both parent and reply. No explicit thread creation
+needed. The UI groups conversations by `thread_id`.
+
+## Context Management
+
+### Session Initialization
+
+`thrum prime` gathers all context in one call:
+
+- Agent identity (name, role, module)
+- Team (active agents and their intents)
+- Inbox (unread messages with summaries)
+- Git context (branch, uncommitted files)
+- Daemon health and sync state
+
+The **SessionStart** hook prompts you to run `/thrum:prime`. The **PreCompact**
+hook auto-saves context to a backup file.
+
+### After Compaction
+
+Context auto-recovers via the PreCompact hook. The agent sees:
+
+1. Their identity and session state
+2. Any unread messages accumulated during compaction
+3. Current team state
+4. Quick command reference
+
+### Identity Persistence
+
+Agent identities are stored in `.thrum/identities/<name>.json` and persist
+across sessions. Registration via `thrum quickstart` is idempotent —
+re-registering with the same name updates the existing identity.
+
+For multi-worktree setups, see [WORKTREES.md](WORKTREES.md) for identity setup.
+
+## Unified Workflow: Thrum + Beads
+
+```bash
+# Find work
+thrum issue ready
+
+# Claim and announce → Beads + Thrum
+bd update bd-123 --status in_progress
+thrum send --to @lead_agent --stdin <<'EOF'
+Starting bd-123
+EOF
+
+# Work, update → Thrum
+thrum send --to @lead_agent --stdin <<'EOF'
+Progress: auth module complete
+EOF
+
+# Complete → Beads + Thrum
+bd close bd-123 --reason "Done with tests"
+thrum send --to @reviewer1 --stdin <<'EOF'
+bd-123 done, ready for review
+EOF
+```

package/assets/skills/thrum/resources/TMUX_SESSIONS.md

@@ -0,0 +1,118 @@
+# Tmux-Managed Sessions
+
+Tmux-managed sessions are the recommended way to run Thrum agents. The daemon
+detects the tmux pane and delivers message notifications directly — zero token
+cost, no background listener needed.
+
+## Why Tmux Sessions
+
+- **Zero-cost message delivery** — daemon nudges the tmux pane directly
+- **No background listener** — eliminates the message-listener sub-agent
+- **Session lifecycle** — create, launch, status, connect, restart, kill
+- **Runtime detection** — reads configured runtime from `.thrum/config.json`
+
+## Quick Start
+
+```bash
+thrum tmux start                    # One-command: create + launch + prime + attach
+```
+
+This creates a tmux session named after the current directory, launches the
+configured runtime (from `config.Runtime.Primary`, default `claude`), runs
+`/thrum:prime` for registration, and attaches.
+
+## Setting Up a New Agent Worktree
+
+Full sequence for a coordinator setting up an agent in a new worktree:
+
+```bash
+# 1. Initialize thrum + beads redirects in the worktree
+cd <worktree-path>
+thrum init                              # Sets up .thrum redirect to main repo
+# Beads: bd init doesn't auto-detect worktrees, so set up the redirect manually:
+mkdir -p .beads && echo /path/to/main/repo/.beads > .beads/redirect
+
+# 2. Create tmux session + register agent identity in one step
+thrum tmux create <name> --cwd <path> \
+  --name <agent> --role <role> --module <mod> --intent '...'
+# alias: thrum tmux quickstart <name> --cwd <path> --name <agent> --role <role> --module <mod>
+
+# 3. Launch the runtime (reads configured runtime from .thrum/config.json)
+thrum tmux launch <name>
+
+# 4. Agent runs /thrum:prime on startup — loads identity + full context
+# 5. Communicate via: thrum send --to @<agent> --body-file msg.md  (or --stdin <<'EOF' heredoc)
+```
+
+`thrum tmux create` requires either quickstart flags (`--name`, `--role`,
+`--module`) or `--no-agent`. Bare `thrum tmux create <name> --cwd <path>` errors
+out.
+
+**Single identity per worktree:** quickstart cleans up any old identity files in
+the worktree. Each worktree has exactly one identity.
+
+**`--no-agent`** skips identity registration — for bare sessions, debugging, or
+non-agent processes:
+
+```bash
+thrum tmux create debug-session --cwd /path --no-agent
+```
+
+Note: `thrum tmux launch` will hard-error on `--no-agent` sessions because
+there's no agent identity to determine the runtime. Either register an agent
+first with `thrum quickstart` inside the pane, or use `tmux create` without
+`--no-agent`.
+
+## Manual Setup (Quick Reference)
+
+```bash
+thrum tmux create <name> --cwd <path> --name <agent> --role <role> --module <mod>
+thrum tmux launch <name>                # Start runtime in session
+thrum tmux connect <name>               # Attach to session
+```
+
+## Session Management
+
+```bash
+thrum tmux status                   # Show all managed sessions with state
+thrum tmux connect                  # Interactive picker for alive sessions
+thrum tmux connect <name>           # Attach directly by name
+thrum tmux kill <name>              # Tear down a session
+```
+
+## Message Delivery
+
+When a message arrives for your agent, the daemon sends a nudge directly to your
+tmux pane. You'll see a notification appear — check your inbox:
+
+```bash
+thrum inbox --unread
+```
+
+For anything older, see [MESSAGING.md](MESSAGING.md) Lifecycle step 6 (search
+instead of paging).
+
+No listener sub-agent, no polling, no CronCreate watchdog. Messages just arrive.
+
+## Session Restart
+
+When the context window is running low, restart with a conversation snapshot
+preserved:
+
+- **Self-initiated:** Run `/thrum:restart` — saves snapshot, notifies
+  coordinator
+- **Coordinator-initiated:** `thrum tmux restart <name>` — **PLAIN, not `--force`.**
+  `--force` **drops the `--model` pin**; a plain restart re-applies it at the
+  readiness probe. Only use `--force` if a plain restart does not take, and then
+  re-pin and verify the model **off the pane** (`runtime-config get` reports what
+  was requested, not what is running).
+- **Automatic:** Configure `restart.auto_threshold` in `.thrum/config.json`
+
+The snapshot is automatically included in `thrum prime` on the next session
+start.
+
+## When Tmux Isn't Available
+
+If tmux is not installed or not practical for your setup, use the background
+message listener pattern instead. See
+[LISTENER_PATTERN.md](LISTENER_PATTERN.md).

package/assets/skills/thrum/resources/WORKTREES.md

@@ -0,0 +1,117 @@
+# Multi-Worktree Coordination
+
+Thrum enables agents in different git worktrees to communicate via a shared
+daemon and git-backed message storage.
+
+## Setup
+
+Use `thrum worktree create` to create a worktree and register an agent in one
+step. This handles git, redirects, identity, and tmux session setup.
+
+```bash
+# Two-step pattern (create + launch)
+thrum worktree create my-feature \
+  --name impl_my_feature --role implementer --module my-feature \
+  --intent "Feature implementation"
+# → creates worktree, registers agent, creates tmux session
+# → output tells you to run: thrum tmux launch my-feature
+
+thrum tmux launch my-feature
+# → starts the runtime (claude/codex/cursor) in the tmux pane
+```
+
+The worktree is created at `<base_path>/<name>` (default
+`~/.workspaces/<repo-name>/<name>`). Branch defaults to `feature/<name>`,
+override with `-b <branch>`.
+
+`worktree create` automatically:
+
+- Creates the git worktree
+- Sets up the `.thrum/` redirect to the main repo
+- Creates a tmux session with the worktree as cwd
+- Runs quickstart inside the pane (PID-isolated, retries if shell init swallows
+  the command)
+- Reports the next-step `tmux launch` command
+
+The agent is **NOT running** until `thrum tmux launch <name>` is called. The
+launch step is what actually starts the AI runtime (claude/codex/etc).
+
+### Worktree without an agent
+
+To set up the worktree without registering an agent, omit the agent
+flags:
+
+```bash
+thrum worktree create my-feature
+# → creates worktree + redirect only
+# → output tells you: thrum tmux create my-feature --cwd <path> --name <agent> --role <r> --module <m>
+```
+
+### Existing worktree
+
+For a worktree that already exists without thrum setup, use `tmux create`
+directly:
+
+```bash
+thrum tmux create existing-feature --cwd /path/to/worktree \
+  --name impl_existing --role implementer --module existing
+thrum tmux launch existing-feature
+```
+
+## Shared Daemon
+
+All worktrees share one daemon instance. The daemon auto-discovers worktrees via
+the shared `.thrum/` directory at the git root.
+
+```bash
+# Start daemon once (from any worktree)
+# Note: thrum init also starts the daemon automatically if not already running
+thrum daemon start
+
+# All worktrees connect to the same daemon
+thrum daemon status    # Shows shared daemon health from any worktree
+```
+
+## Cross-Worktree Messaging
+
+```bash
+# From main worktree
+thrum send --to @feature_impl --stdin <<'EOF'
+Feature branch ready for integration
+EOF
+
+# From feature worktree
+thrum inbox    # Sees message from @main_coordinator
+thrum sent     # Verifies what this worktree sent and who read it
+thrum reply <msg-id> --stdin <<'EOF'
+Integration tests passing, ready to merge
+EOF
+thrum message read --all  # Mark all messages as read
+```
+
+## File Coordination
+
+Check which agent is editing a file before making changes:
+
+```bash
+thrum who-has src/auth/login.ts
+# Output: @feature_impl (active)
+
+# Coordinate via message
+thrum send --to @feature_impl --stdin <<'EOF'
+Need to edit login.ts, are you done?
+EOF
+```
+
+## Sync
+
+Messages sync via git. The daemon handles push/pull automatically. Force sync if
+needed:
+
+```bash
+thrum sync force
+thrum sync status
+```
+
+For multi-machine setups, ensure all machines can push/pull to the same git
+remote.

package/assets/skills/thrum-memory/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: thrum-memory
+description: "Use when capturing or querying structured memories (session summaries, architectural decisions, restart snapshots, agent rules) via the thrum memory CLI. Loads decision flowchart, kind taxonomy, default-safe behaviors, and pointers to advanced sub-skills."
+allowed-tools: "Bash(thrum memory:*)"
+version: "0.11.0"
+license: "Apache-2.0"
+---
+
+# thrum memory — capture and query structured memories
+
+## When to use thrum memory vs. other stores
+
+Just learned something that future work should respect? → `thrum memory create`
+(decide kind below).
+
+Transient task state (in-progress work, current session context)? → `bd update`
+/ `bd comments` (per-task notes).
+
+Long-form project narrative (architecture decisions, release status)? → memory
+of kind `arch_decision` or `session_summary` (the integration brainstorm will
+wire these into prime-assembly later).
+
+Code documentation (CLAUDE.md, READMEs, in-file comments)? → edit the file
+directly; memory is for structured records, not docs.
+
+## Kind taxonomy at a glance
+
+- `session_summary` — what shipped in a session (replaces ad-hoc session notes)
+- `arch_decision` — long-lived architectural decision; can be superseded later
+- `current_state` — point-in-time state snapshot; expires fast
+- `epic_status` — one row of "Open Epics / Active Work"
+- `worktree_status` — one worktree-table row; expires per session
+- `stable_infra` — long-lived infrastructure entry
+- `resume_snapshot` — per-agent restart blob (scope=agent)
+- `agent_rule` — rule/preference for future sessions (scope=role or
+  scope=project)
+- `comment` — comment on a parent memory (`child_of: <parent-id>`)
+
+## Top operations (the 80% case)
+
+Create with all three zoom levels (recommended; warns via MEM-010 otherwise):
+
+```bash
+thrum memory create --kind arch_decision \
+  --title "Tailscale-only sync" \
+  --oneline "Removed git a-sync; Tailscale peering is sole sync mechanism" \
+  --short @short.md --full @full.md \
+  --tag substrate,sync
+```
+
+See `memory-write-discipline` for prose-into-a-command conventions.
+
+Search by tag + kind, default limit 10:
+
+```bash
+thrum memory search --tag substrate --kind arch_decision
+```
+
+Show a single memory by ID:
+
+```bash
+thrum memory show thrum-mem-01HQXZP3V8K2N7M0YJWQ8R5T6F
+```
+
+Edit a single field (other zoom levels stay intact; only changed-zoom embeddings
+re-queue):
+
+```bash
+thrum memory edit <id> --short @newshort.md
+thrum memory edit <id> --add-tag v0.11 --rm-tag draft
+```
+
+Link an edge:
+
+```bash
+thrum memory link <new-id> supersedes <old-id>
+thrum memory link <child-id> child_of <parent-id>
+```
+
+## Default-safe behaviors
+
+- `--limit 10` by default for search (memory body_full is 5-50× larger than
+  typical messages; bounded context pollution). `--limit 25` or higher is a
+  one-flag opt-in for deeper exploration.
+- `status=active` default filter (use `--status all` to include
+  superseded/purged).
+- **Scope is an ASSEMBLY filter** (NOT visibility/access control) —
+  `memory.search` returns everything matching your predicates regardless of
+  scope unless `--scope` is explicitly passed. Scope only affects which memories
+  the (deferred) default assembler folds into an agent's prime context.
+
+## Feature-scoped queries — use tags, not scope
+
+Scope is closed (`project / agent / role`). For "feature-scoped" filtering
+(e.g., "show me memories about the watcher-substrate feature"), use the
+`feature-<name>` tag-naming convention:
+
+```bash
+thrum memory create --kind session_summary --tag feature-watcher-substrate,substrate ...
+thrum memory search --tag feature-watcher-substrate --limit 10
+thrum memory search --tag substrate --kind arch_decision  # one tag per query; for OR, run one search per tag
+```
+
+Convention only — no code enforces the `feature-` prefix, but discoverability
+across agents/sessions depends on consistency.
+
+## When you need more
+
+- For RAG / `--near` queries / complex predicates / hint code interpretation:
+  load the `memory-search-advanced` skill
+- For edges, hierarchy, supersede semantics, comments-as-memories: load the
+  `memory-curate` skill
+- For audit history, undelete, hard-delete confirmation flow: load the
+  `memory-audit-recover` skill
+
+## First-time setup (configuration)
+
+Embedding adapter is opt-in. Default config disables RAG; full-text search
+(`--grep`) works without it. To enable RAG:
+
+```bash
+thrum config set llm.embedding.enabled true
+thrum config set llm.embedding.provider ollama
+thrum config set llm.embedding.base_url http://localhost:11434
+thrum config set llm.embedding.model "granite-embedding:30m-english"
+```
+
+For non-English projects use `granite-embedding-multilingual-97m` instead.
+
+`id_prefix` for memory IDs is auto-derived from your repo (git remote URL →
+main-worktree basename → CWD basename, with normalization). To override:
+
+```bash
+thrum config set id_prefix "my-repo"
+```
+
+Rate limit and backfill knobs live under `embedding.max_per_minute` (default 60)
+and `embedding.backfill_on_boot` (default true).