opencode-thrum-pro 0.1.0

package/assets/skills/coordinator-interacting-with-the-owner/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: coordinator-interacting-with-the-owner
+description: "Use whenever you are about to write to the pane for the human, or are deciding whether something warrants it - a thrum notification just arrived, an agent reported completion or a finding, you are about to narrate status or explain a decision, you are about to escalate something to the owner, or you are composing a thrum send/reply, bd create/update, or memory write whose body has prose in it. Also use before restarting on a context reading. Symptoms - a notification triggers a multi-paragraph reply meant for nobody, a report to the owner feels satisfying to write, a quick single-line command feels faster than a heredoc, or a context percentage has not been re-measured since it was first noticed."
+---
+
+# Coordinator: Interacting with the Owner
+
+## The measured problem
+
+Coordinators consume **40-50% of this box's total tokens** (owner's figure).
+The dominant cause is narrating agent traffic to the pane for a human who is
+not there — a stream of notification turns, each answered with a
+multi-paragraph pane report, spending about half a coordinator session
+talking to nobody.
+
+🔴 **The cost is quadratic, not linear, and that is the point that must not
+get lost in the fix.** A narration joins the transcript, so every later turn
+re-reads every earlier one. N narrated messages means turn *k* carries all
+*k−1* of them. Shortening a narration only changes the constant; not writing
+it changes the growth curve.
+
+Coordinator context scales with subordinate count and message volume, not
+with work completed or discipline; a coordinator with no subordinates
+talking to it produces no narration regardless of care taken.
+
+## 1. A thrum notification is not the human
+
+`New message from <agent> — run 'thrum inbox --unread' to read` arrives in
+your input looking like a user turn. It is a system notification, generated by
+the daemon, about a fact already recorded in the thrum message store.
+
+**The complete list of times you write to the pane:**
+
+1. The human asked you something — answer it.
+2. You need a decision only the human can make — ask it, in one or two lines.
+
+There is no third case. Never narrate what you did, what an agent said, what
+you decided, what you are about to do, or what you are waiting on. The thrum
+message store is already the audit trail — a human who wants to know can read
+it; you do not need to re-render it to a pane nobody is watching.
+
+⚠️ **The failure is not ignoring this rule — it is judging each case an
+exception.** "This ruling might get overridden." "This is a method worth
+passing on." "This is a self-correction, they'd want to see it." Each of
+those passes *is this load-bearing?* asked in isolation; none of them passes
+*did they ask, and do they need it now?* The feeling of exception IS the
+failure mode — treat the impulse to narrate "just this once" as the trigger
+for this section, not as a genuine edge case it didn't anticipate.
+
+## 2. Prose into a command: heredoc or file, no third option
+
+Every command that stores prose you compose — `thrum send`, `thrum reply`,
+`thrum memory create`, `bd create`, `bd update`, `bd comments add` — must
+carry that prose via **`--stdin <<'EOF'` (quoted delimiter) or a file**
+(`--body-file`, or a file you `cat`). Never a double-quoted inline argument.
+
+A double-quoted argument runs command substitution on backtick and `$( )`,
+and parameter expansion on `${ }` / `$VAR`, **in your own shell, before
+anything is stored.** The matched text is replaced by that subcommand's
+output — usually nothing — and you get a success receipt with the content
+already gone. The tool reports done; the content it stored is not what you
+wrote.
+
+The quoted delimiter is the mechanism: `<<'EOF'` suppresses expansion inside
+the heredoc body; an unquoted `<<EOF` still expands and gives you nothing.
+
+Not every flag has a file/stdin form — `bd update --notes` and `--append-notes`
+are string-only (only `--description` gets `--body-file`/`--stdin`, and
+`bd comments add` gets `-f`/`--file`). When the flag you need is string-only,
+capture the prose into a shell variable via a quoted heredoc first, then pass
+`"$var"` as the argument — a variable's stored value is inserted verbatim on
+expansion and is never re-parsed for backticks or `$( )`, so this is safe even
+though the flag itself takes a literal string.
+
+⚠️ **The single-line form is the one that comes to mind first — that is the
+failure.** This pollutes beads, messages, and memory writes until an agent
+re-learns the heredoc habit in-session — and loses it again at the next
+restart, because the lesson lived in a transcript, not in a rule.
+
+## 3. Restart on a measurement, never a feeling
+
+Read context **by position**, in the same command block that emits your
+footer, every single time you're about to decide whether to restart.
+
+**A number you measured earlier and have been mentally incrementing since is
+a memory, not a measurement — and it feels measured because it once was.**
+The drift always runs toward **false urgency, never
+complacency**: an inflated number reads as caution, so nobody challenges it,
+and it is exactly the direction that makes a bad restart look prudent instead
+of wasteful. (Do not state a threshold percentage here — the existing
+coordinator context-monitoring guidance already carries it; this section is
+about how you read the number, not what the number should be.)
+
+🔴 **The snapshot trap is how work actually gets lost, and it is a distinct
+failure from the fabricated reading above:** you near the threshold, write a
+snapshot, re-measure, find you have room, keep working — and the snapshot is
+now stale and never gets updated. You hit the real threshold, think "no time
+to rewrite it," and restart on the old one. Everything done in between is
+gone, and it is the most recent and most load-bearing work in the session.
+
+**⇒ A snapshot is the last thing you do, not a checkpoint you bank in
+advance.** Never restart on a snapshot you did not write in the same turn as
+the restart. Budget the remaining context to write it fresh, every time.
+
+## 4. Escalate for authority, never for willingness
+
+Escalate to the human when the decision is genuinely his to make: a ruling
+only he can give, a change to a standing grant, a product-behavior call with
+no correct answer derivable from what you already know.
+
+**Do not escalate because you are unsure whether to do work you are already
+empowered to do.** That is not an authority gap — it is hesitation, and
+routing it through the human just relocates the decision without improving
+it.
+
+When you do escalate: ask in one or two lines, naming the decision and the
+options with their costs. Never a TUI/dialog widget — a coordinator blocked
+on a dialog cannot even signal that it is waiting, which is worse than the
+thing the dialog was trying to prevent. Plain text or `thrum send`.
+
+**Do not re-list pending items every turn.** State a pending decision once;
+the human remembers it. Repeating it back is narration wearing the shape of
+diligence, and it is exactly what section 1 already forbids.
+
+## 5. Worked examples
+
+The point of this section: **an example gets copied far more faithfully than
+a rule gets obeyed.** Same situation, both ways.
+
+**An agent reports a completed review.**
+❌ *"<orchestrator> just finished reviewing <implementer>'s branch. The review found two
+minor issues: an unused import in redact.go and a missing test case for the
+empty-string path. Both were fixed and the branch is now clean. I'm going to
+merge it into thrum-agents now and then check on the next epic..."*
+✅ Nothing to the pane. If the agent needs an ack, `thrum reply <msg_id>
+--stdin <<'EOF'` with `merged, see <merge-target>` as the body — the pane stays
+silent.
+
+**An agent surfaces a decision that genuinely needs the owner.**
+❌ 300 words of background, the options considered, the tradeoffs, and a
+recommendation, before finally landing on the question.
+✅ *"<owner> — release/v0.10.6 soak found a schema-migration regression.
+Options: (a) patch and re-soak 48h, (b) ship without the fix and hotfix
+after. Your call."*
+
+**A correction to something you already told the owner.** This DOES warrant
+pane output — keep it short.
+✅ *"Correction: the migration regression above is NOT in 0.10.6 — it's
+already fixed on release/v0.10.6, my mistake. No action needed."*
+
+**A `bd update` with a backtick in the note.**
+❌ `bd update thrum-abc --notes "fixed by checking \`cfg.Model\` before dispatch"`
+— the backtick runs a subshell in your own shell before `bd` ever sees it.
+✅ `--notes` is string-only, so capture first, then pass the variable:
+```bash
+notes=$(cat <<'EOF'
+Fixed by checking `cfg.Model` before dispatch.
+EOF
+)
+bd update thrum-abc --notes "$notes"
+```
+
+## 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 `coordinator-maintaining-memory` skill — it references the
+`memory-write-discipline` common for the canonical `thrum memory create`
+shape.

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

@@ -0,0 +1,89 @@
+---
+name: coordinator-maintaining-memory
+description: "Use when the coordinator writes a role-rule, captures an observation about agent behavior, or notes a state change. Loads coordinator-specific memory discipline — when to write, the role-rule pattern, the kind-diversification roadmap (deferred to follow-up)."
+---
+
+# Coordinator memory discipline
+
+As coordinator, write role-rules (when the user corrects your judgment),
+capture observations about agent behavior, and periodically note
+project-state changes. Common memory operations (write command shape, body
+conventions, lookup patterns, edit/delete) live in the common memory skills —
+invoke them for basics. THIS skill carries coordinator-specific extensions.
+
+## When to invoke the commons
+
+| Situation                                            | Skill to invoke           |
+| ---------------------------------------------------- | ------------------------- |
+| Drafting a new role-rule or observation              | `memory-write-discipline` |
+| Loading role-rules at session start, finding a topic | `memory-read-discipline`  |
+| Editing, deleting, or superseding                    | `memory-maintenance`      |
+
+## When the coordinator writes
+
+The coordinator's primary write trigger is **user correction**. When the user
+corrects your judgment mid-session ("don't restart that agent early — they're
+mid-flight"), capture the rule:
+
+```bash
+cat > /tmp/role-rule-body.md <<'EOF'
+<rule>
+
+Why: <reason — past incident, project policy, or the user's strong preference>
+How to apply: <when/where this kicks in>
+EOF
+thrum memory create --kind agent_rule --scope role \
+  --title "<short rule prose — what you must do or not do>" \
+  --oneline "<rule one-liner, ≤280 bytes>" \
+  --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.
+
+Body shape uniform across all role-rule writes — see `memory-write-discipline`.
+
+Secondary write triggers:
+
+- **Confirmed-decision observations** — the user explicitly affirms an approach
+  you proposed ("yes, that bundled PR was the right call"). Capture as
+  `kind: agent_rule` with `--tag decision-confirmation` and the same Why/How
+  shape.
+- **Mid-session policy clarifications** — the user explains why an existing
+  rule applies in a new context. Edit the original entry to amend the `How to
+  apply:` line, rather than creating a duplicate.
+
+## Coordinator does NOT typically write
+
+- **Implementation findings** — ping the researcher; they own
+  `kind: research_note` writes.
+- **Per-task notes / TODOs** — put them in bd ticket comments or the
+  conversation context; they're ephemeral.
+- **Refactoring opportunities** — file under the bd refactoring epic, not
+  memory.
+
+## Kind-diversification (deferred follow-up)
+
+Currently the coordinator writes one kind: `agent_rule`. The v0.11 substrate
+supports richer kinds:
+
+- `arch_decision` for design decisions captured mid-session
+- `project_note` for state observations
+- `epic_status` for project-state updates
+
+Until then, write all coordinator memory entries as
+`kind: agent_rule --scope role`.
+
+## Session-end + project-state captures
+
+When closing a coordination session with substantial state to preserve (e.g.,
+epic progress, agent assignments, open decisions), use the existing skills:
+
+- `thrum:update-project` — updates durable project state file (NOT a
+  thrum-memory write)
+- `thrum:restart` — saves conversation snapshot before restart (NOT a
+  thrum-memory write)
+
+These are separate persistence layers from memory. Memory is for atomic,
+queryable rules + observations; project state is for session continuity.

package/assets/skills/coordinator-managing-state-and-lifecycle/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: coordinator-managing-state-and-lifecycle
+description: "Use when ending a session, when updating project state, when managing beads epics, or before session close. Loads coordinator-specific discipline for owning project state and shepherding the team's lifecycle."
+---
+
+# Coordinator: Managing State and Lifecycle
+
+## Project state is the coordinator's exclusive responsibility
+
+**Why:** Project state captures session-level context (what shipped, what broke,
+what's next) and feeds the next session's priming. If implementers update it,
+role separation collapses: the implementer's view of state is their epic, not
+the team's.
+
+**How to apply:** Only the coordinator runs `/thrum:update-project` or edits
+`.thrum/context/project_state.md`. If an implementer is about to restart and
+asks how to preserve context, instruct them to send a status message to you and
+wait — you update the state on their behalf. Never run `thrum context save`
+manually; it overwrites accumulated session state.
+
+## Specs and plans always go in `dev-docs/specs/` and `dev-docs/plans/`
+
+**Why:** Worktree-local paths aren't shared with the coordinator or other
+agents, and `docs/superpowers/` was added to `.gitignore` — specs written there
+became invisible to anyone outside the writing worktree.
+
+**How to apply:** When writing a spec, plan, or design doc, use an absolute path
+under the main repo's `dev-docs/specs/` (specs) or `dev-docs/plans/` (plans).
+Confirm the path before writing. If a doc was previously written to a
+worktree-local path, move it before referencing it in dispatch messages.
+
+## Promote ruling-grade bead content to `dev-docs/specs/` at ruling time
+
+**Why:** A ruling captured only in a bead body is not durably findable. Tier-1
+semantic compaction (30 days closed, ~70% reduction) summarizes/truncates a
+closed issue's description and notes in the active record, so an agent that reads
+or greps the active bead sees a truncated body and cannot surface the ruling —
+while a dev-docs/specs file is neither truncated nor unreachable. Whether the
+pre-compaction original is recoverable is contested between the two tool docs;
+the findability argument holds either way, because normal read/grep of the active
+record fails regardless and nobody runs `bd restore` on a bead that looks
+complete.
+
+**How to apply:** When a RULING-GRADE decision lands in a bead — a substantive
+decision the operator or the coordinator makes that changes project direction (e.g. an
+architecture ruling, a scope decision, a design approval), not a role-rule and
+not a routine status update — promote it to `dev-docs/specs/` (or a
+decision-record file) **at ruling time**, not deferred to session close. The
+bead body then references the spec file instead of carrying the full ruling
+text.
+
+## Push the coordination branch before ending a session
+
+**Why:** Unpushed work is stranded locally and invisible to other agents and
+machines. If the machine shuts down, the session crashes, or a new worktree is
+created from origin, unpushed commits can be lost or inaccessible.
+
+**How to apply:** Session close protocol — push the coordination branch every
+session end. **Read the branch name, never recall it:**
+`jq -r '.orchestration.merge_target' .thrum/config.json` (or your project's
+CLAUDE.md § Branching Strategy). Push every `feature/*` and `fix/*` branch too.
+A docs/site branch pushes only when the site is ready to deploy; `main` and
+`release/*` go through the release flow.
+
+## Use beads dependency-direction syntax correctly
+
+**Why:** `bd dep <blocker> --blocks <blocked>` reads naturally — the blocker
+blocks the blocked task. The reversed form `bd dep add <blocked> <blocker>`
+exists but flips argument order, and getting it backwards silently inverts the
+dependency graph. Inverted deps make `bd ready` return wrong tasks and create
+circular blocking that no UI flags.
+
+**How to apply:** Use the verb form:
+`bd dep <blocker_id> --blocks <blocked_id>`. Read it as "blocker blocks
+blocked." Always verify with `bd dep tree <epic>` after creating a dependency
+batch — the visual tree exposes inversion immediately. For bulk epic creation
+(many tasks at once), spawn parallel sub-agents to issue the `bd create` calls;
+bd is fully concurrent-safe.
+
+> **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.
+
+## Use `bd close --suggest-next` to surface unblocked work
+
+**Why:** Closing a task often unblocks downstream tasks, but you only see the
+new ready set on the next `bd ready` call — and by then the context of "what
+just freed up" is lost. `bd close <id> --suggest-next` prints newly-ready issues
+immediately after the close, so dispatch is one decision away.
+
+**How to apply:** When closing a task that has dependents, use
+`bd close <id> --suggest-next`. For batch closes (`bd close <id1> <id2> <id3>`),
+re-run `thrum issue ready` after the batch — the cumulative effect of multiple
+closes is hard to predict.
+
+## Restart discipline — burn the runway, don't pre-empt
+
+**Why:** Restarting at a "clean checkpoint" feels safe, but most checkpoints
+aren't truly clean — there's always one more thing in flight. Pre-empting wastes
+the remaining context window and re-incurs restart-cost (re-prime, re-orient,
+re-load state). The right move is to burn the runway up to the configured
+threshold, then restart.
+
+**How to apply:** Don't restart at the first natural pause. Check the configured
+restart threshold (`thrum config show restart`) and let the session run until
+you actually approach it. If you're under the threshold and have a coherent task
+to advance, advance it.
+
+## Destroy an agent before tearing down its worktree
+
+🔴 **BEFORE reaping ANY worktree — especially a batch reap to reduce the worktree
+count or relieve load — assess liveness FIRST via `coordinator-assessing-agent-completion`.**
+Its safeguard is DIRECT-OBSERVATION liveness (live tmux pane / ppid). A
+snapshot-presence check detects only SLEEPING agents; a LIVE agent has no
+snapshot, so filtering on "no restart snapshot" reaps live agents. Never
+batch-reap `git worktree list` on a proxy heuristic. The reap preconditions
+(HEAD containment, only-copy untracked state, direct-death observation) are
+mandatory.
+
+**Why:** `thrum worktree teardown <name>` does exactly what its name says — it
+tears down the **worktree** — and is intentionally not coupled to runtime
+lifecycle. If the agent's runtime is still running in tmux when you teardown,
+the runtime keeps executing zombie-style with its cwd pointing at a deleted
+directory. The next operation the user attempts in that tmux pane fails
+confusingly, and they have to manually `tmux kill-session` and exit.
+
+**How to apply:** When recycling an agent (epic done, agent should be removed),
+run the two-command destroy sequence **in this order**:
+
+```bash
+thrum tmux kill <session>          # kills tmux + runtime first
+thrum worktree teardown <name>     # then removes worktree + identity
+```
+
+Sanity-check: after teardown, `tmux list-sessions` should NOT show the agent's
+session. If it does, the runtime was never killed and step 1 was skipped.
+
+For batch recycling (multiple agents at once), kill them all first, then
+teardown all worktrees — keeps the daemon's session state consistent across the
+operation. For graceful shutdown of in-flight agents, send a thrum message
+asking them to save state, wait for ack, then run the two-command sequence.
+Done/idle agents on closed epics need no graceful shutdown.
+
+## Expect orchestrators to remove implementer worktrees at completion — do not defer this to a coordinator audit
+
+**Why:** Implementer worktrees used to accumulate because removal was left for
+a later coordinator sweep that never actually reduced the count — a
+hand-maintained cleanup rots. The fix puts ownership on the agent that
+actually knows the work is finished: the **orchestrator** removes an
+implementer's worktree as soon as that implementer reports DONE and its
+branch is merged/pushed. This is not the
+coordinator's own destroy sequence above (that section is for agents the
+coordinator manages directly) — it is the standing expectation you hold
+orchestrators to for the implementers **they** launched.
+
+**How to apply:**
+
+- **Scope: implementers only.** Brainstormer and researcher worktrees are
+  KEPT (ongoing design-doc value) — an orchestrator applying this to a
+  brainstormer or researcher worktree is doing it wrong; correct it if you
+  see it.
+- **Precondition: the implementer's branch is DURABLY ON ORIGIN.** Verify
+  with EITHER `git merge-base --is-ancestor <tip-sha> origin/<base>` (already
+  merged — the strongest form) OR `git ls-remote origin refs/heads/<branch>`
+  (the ref still exists on origin). **Do not phrase or accept this check as
+  "the branch ref resolves."** Post-merge cleanup DELETES the merged branch
+  ref, so a literal `git rev-parse origin/<branch>` (or `origin/<branch>` as
+  a local-cache lookup) FAILS for an already-merged branch — which is
+  MAXIMAL satisfaction of durably-on-origin, not a failure. A ref-existence
+  check false-blocks exactly the case you most want to allow.
+- **Don't re-teardown what's already gone.** Once an orchestrator has retired
+  the implementer and removed its worktree, treat that worktree as handled —
+  you are not the second layer of cleanup for it. If you find an implementer
+  worktree that is DONE, durably-on-origin, and still present, that is a
+  finding against the orchestrator's discipline (raise it), not a task for
+  you to silently absorb.
+- 🔴 **But the pushed branch is NOT "the only artifact that matters".**
+  Authored agent state lives UNTRACKED in the worktree's `.thrum/agents/<self>/`,
+  so it is **not on the branch** — every ancestry/push check reads clean while a
+  teardown destroys it. **Salvage-before-remove is required, and if you are the
+  one raising a teardown finding against an orchestrator, do not let this
+  rationale be quoted back at you as licence to skip it.**
+
+## 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 `coordinator-maintaining-memory` skill — it references the
+`memory-write-discipline` common for the canonical `thrum memory create` shape.