opencode-thrum-pro 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/assets/commands/thrum-_deviations-protocol.md +87 -0
  2. package/assets/commands/thrum-_generator-idempotency-protocol.md +15 -0
  3. package/assets/commands/thrum-_project-rules-protocol.md +18 -0
  4. package/assets/commands/thrum-_snapshot-protocol.md +265 -0
  5. package/assets/commands/thrum-_stamp-protocol.md +112 -0
  6. package/assets/commands/thrum-_verify-before-write-protocol.md +27 -0
  7. package/assets/commands/thrum-inbox.md +22 -0
  8. package/assets/commands/thrum-load-context.md +17 -0
  9. package/assets/commands/thrum-overview.md +17 -0
  10. package/assets/commands/thrum-prime.md +30 -0
  11. package/assets/commands/thrum-quickstart.md +14 -0
  12. package/assets/commands/thrum-reply.md +28 -0
  13. package/assets/commands/thrum-restart-extended.md +195 -0
  14. package/assets/commands/thrum-restart.md +293 -0
  15. package/assets/commands/thrum-send.md +31 -0
  16. package/assets/commands/thrum-sleep-extended.md +186 -0
  17. package/assets/commands/thrum-sleep.md +212 -0
  18. package/assets/commands/thrum-team.md +12 -0
  19. package/assets/commands/thrum-update-project.md +259 -0
  20. package/assets/commands/thrum-wait.md +14 -0
  21. package/assets/skills/adversarial-critique/SKILL.md +242 -0
  22. package/assets/skills/brainstorm-queue-aware/SKILL.md +167 -0
  23. package/assets/skills/brainstorm-steward/SKILL.md +181 -0
  24. package/assets/skills/choosing-subagent-models/SKILL.md +244 -0
  25. package/assets/skills/closing-findings-while-warm/SKILL.md +104 -0
  26. package/assets/skills/configure-roles/SKILL.md +229 -0
  27. package/assets/skills/coordinator-assessing-agent-completion/SKILL.md +205 -0
  28. package/assets/skills/coordinator-assessing-agent-completion/scan.py +117 -0
  29. package/assets/skills/coordinator-branch-split-on-block/SKILL.md +168 -0
  30. package/assets/skills/coordinator-context-monitoring/SKILL.md +674 -0
  31. package/assets/skills/coordinator-dispatching-work/SKILL.md +288 -0
  32. package/assets/skills/coordinator-hotpath-merge-gate/SKILL.md +522 -0
  33. package/assets/skills/coordinator-interacting-with-the-owner/SKILL.md +171 -0
  34. package/assets/skills/coordinator-maintaining-memory/SKILL.md +89 -0
  35. package/assets/skills/coordinator-managing-state-and-lifecycle/SKILL.md +192 -0
  36. package/assets/skills/coordinator-merging-code/SKILL.md +331 -0
  37. package/assets/skills/coordinator-philosophy-merge-gate/SKILL.md +442 -0
  38. package/assets/skills/coordinator-plan-reconcile-gate/SKILL.md +198 -0
  39. package/assets/skills/coordinator-post-restart-sweep/SKILL.md +135 -0
  40. package/assets/skills/coordinator-running-autonomous-feature-development/SKILL.md +199 -0
  41. package/assets/skills/coordinator-running-brainstorm-cycles/SKILL.md +654 -0
  42. package/assets/skills/coordinator-running-review-cycles/SKILL.md +153 -0
  43. package/assets/skills/coordinator-single-responsibility-merge-gate/SKILL.md +14 -0
  44. package/assets/skills/diagnosing-fleet-and-daemon/SKILL.md +255 -0
  45. package/assets/skills/efficient-multi-agent-research/SKILL.md +177 -0
  46. package/assets/skills/fixing-documentation-errors/SKILL.md +258 -0
  47. package/assets/skills/implementer-maintaining-memory/SKILL.md +84 -0
  48. package/assets/skills/implementer-orchestrating-execution/SKILL.md +125 -0
  49. package/assets/skills/implementer-receiving-dispatch/SKILL.md +127 -0
  50. package/assets/skills/implementer-receiving-review-feedback/SKILL.md +125 -0
  51. package/assets/skills/implementer-status-and-handoff/SKILL.md +150 -0
  52. package/assets/skills/implementer-tdd-and-quality/SKILL.md +99 -0
  53. package/assets/skills/memory-audit-recover/SKILL.md +153 -0
  54. package/assets/skills/memory-curate/SKILL.md +139 -0
  55. package/assets/skills/memory-maintenance/SKILL.md +87 -0
  56. package/assets/skills/memory-read-discipline/SKILL.md +164 -0
  57. package/assets/skills/memory-search-advanced/SKILL.md +217 -0
  58. package/assets/skills/memory-write-discipline/SKILL.md +135 -0
  59. package/assets/skills/orchestrate/SKILL.md +795 -0
  60. package/assets/skills/persistent-watcher-archetype/SKILL.md +225 -0
  61. package/assets/skills/prime-agent/SKILL.md +92 -0
  62. package/assets/skills/project-hotpath-gate/SKILL.md +255 -0
  63. package/assets/skills/project-philosophy/SKILL.md +418 -0
  64. package/assets/skills/project-philosophy/resources/philosophy-template.md +155 -0
  65. package/assets/skills/project-philosophy/resources/reliability-class-library.md +653 -0
  66. package/assets/skills/project-setup/SKILL.md +1007 -0
  67. package/assets/skills/project-setup/resources/implementation-agent.md +826 -0
  68. package/assets/skills/researcher-answering-queries/SKILL.md +100 -0
  69. package/assets/skills/researcher-investigating/SKILL.md +152 -0
  70. package/assets/skills/researcher-maintaining-memory/SKILL.md +176 -0
  71. package/assets/skills/state-migration/SKILL.md +54 -0
  72. package/assets/skills/thrum/SKILL.md +161 -0
  73. package/assets/skills/thrum/resources/ANTI_PATTERNS.md +132 -0
  74. package/assets/skills/thrum/resources/BOUNDARIES.md +56 -0
  75. package/assets/skills/thrum/resources/CLI_REFERENCE.md +1066 -0
  76. package/assets/skills/thrum/resources/IDENTITY.md +49 -0
  77. package/assets/skills/thrum/resources/LISTENER_PATTERN.md +64 -0
  78. package/assets/skills/thrum/resources/MESSAGING.md +163 -0
  79. package/assets/skills/thrum/resources/TMUX_SESSIONS.md +118 -0
  80. package/assets/skills/thrum/resources/WORKTREES.md +117 -0
  81. package/assets/skills/thrum-memory/SKILL.md +138 -0
  82. package/assets/skills/trace-spec-to-plan/SKILL.md +104 -0
  83. package/assets/skills/trace-spec-to-plan/resources/sweep-agent-prompt.md +57 -0
  84. package/assets/skills/update-queue/SKILL.md +149 -0
  85. package/assets/skills/using-the-queue/SKILL.md +172 -0
  86. package/assets/skills/using-thrum-state/SKILL.md +104 -0
  87. package/assets/skills/verify-against-plan/SKILL.md +323 -0
  88. package/assets/skills/verify-against-source/SKILL.md +237 -0
  89. package/assets/skills/watcher-archetype/SKILL.md +84 -0
  90. package/assets/skills/writing-durable-markdown/SKILL.md +66 -0
  91. package/dist/hooks/block-sync-cd.d.ts +9 -0
  92. package/dist/hooks/block-sync-cd.js +71 -0
  93. package/dist/hooks/block-sync-cd.test.d.ts +1 -0
  94. package/dist/hooks/block-sync-cd.test.js +61 -0
  95. package/dist/hooks/shell-env.d.ts +8 -0
  96. package/dist/hooks/shell-env.js +22 -0
  97. package/dist/index.d.ts +6 -0
  98. package/dist/index.js +25 -0
  99. package/dist/installer.d.ts +2 -0
  100. package/dist/installer.js +86 -0
  101. package/package.json +49 -0
@@ -0,0 +1,14 @@
1
+ ---
2
+ description: Block until a message arrives
3
+ ---
4
+
5
+ Block until a message arrives or timeout expires. Used by the message-listener
6
+ pattern.
7
+
8
+ ```bash
9
+ thrum wait # Default 30s timeout
10
+ thrum wait --timeout 120s # 120 seconds
11
+ thrum wait --after -15s --json # Include messages sent up to 15s ago; JSON output
12
+ ```
13
+
14
+ See LISTENER_PATTERN.md resource for the full background listener template.
@@ -0,0 +1,242 @@
1
+ ---
2
+ name: adversarial-critique
3
+ description: "Use when an implementer is blocked mid-work by a design flaw, contradiction, or unforeseen fork with 2-3 ways to resolve it - produces a defended pick that unblocks the work and leaves an audit trail so the decision can be revisited if it later proves wrong"
4
+ ---
5
+
6
+ # Adversarial Critique: Resolving a Blocking Design Fork Mid-Implementation
7
+
8
+ ## Overview
9
+
10
+ Stress-test a mid-implementation design fork by dispatching sub-agents that
11
+ argue opposing options across three structured rounds. Produces a defended pick
12
+ with invariants and acceptance criteria — not a "both approaches work" summary.
13
+ The artifact left on disk is an audit trail: if the decision proves wrong later,
14
+ future readers can see exactly why it was made and what was considered.
15
+
16
+ ## When to use
17
+
18
+ - Implementation work has hit a blocker — a flaw, contradiction, or unforeseen
19
+ fork — and can't continue until a decision is made
20
+ - The resolution has 2-3 plausible paths, each with real tradeoffs
21
+ - The decision is substantive enough that "just pick one" would likely be
22
+ regretted
23
+ - An audit trail lets the decision be revisited if it proves wrong later
24
+
25
+ ## When NOT to use
26
+
27
+ - Upfront design before implementation starts — use `superpowers:brainstorming`
28
+ instead
29
+ - Obvious choices where any option works — just pick and continue
30
+ - Emergencies where speed beats rigor
31
+ - Pure research questions — use `superpowers:efficient-multi-agent-research`
32
+ - 4+ options — decompose the decision or narrow first
33
+
34
+ ## Inputs
35
+
36
+ **Required:**
37
+
38
+ - Topic (one-sentence statement of the blocker)
39
+ - 2 or 3 options, each with a short name and one-sentence description
40
+
41
+ **Strongly recommended:**
42
+
43
+ - Context block: relevant file excerpts, prior art, schema snippets, constraints
44
+ - Engagement axes: cross-cutting concerns the debate MUST address. Example axes
45
+ that worked on a real debate (pick analogues for your domain):
46
+ - cross-daemon semantics
47
+ - schema impact
48
+ - test strategy
49
+ - API surface
50
+ - blast radius
51
+
52
+ Without these, sub-agents re-grep the codebase and produce generic arguments.
53
+ Pre-assembled context is the difference between a real debate and a shallow one.
54
+
55
+ ## The three rounds
56
+
57
+ > **Model tiers:** pass an explicit `model:` on every dispatch — `sonnet`
58
+ > (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
59
+ > operator-ask or a skill step that names it. See the
60
+ > `choosing-subagent-models` skill for the full policy.
61
+
62
+ Dispatch one sub-agent per option, in parallel (single message, multiple Agent
63
+ tool calls). `model: "sonnet"` for all dispatches — quality matches Opus on
64
+ structured critique at a fraction of the cost.
65
+
66
+ ### Round 1 — opening positions
67
+
68
+ Each agent gets: topic, context block, engagement axes, their assigned option.
69
+ Word limit ~450. Required output:
70
+
71
+ - **Argument** (why this option)
72
+ - **Proposed shape** (concrete — API, struct, contract)
73
+ - **Pre-emptive rebuttal** (predict opponent's strongest attack, answer it now)
74
+
75
+ The pre-emptive rebuttal forces steelmanning and prevents R2 surprise-reveal.
76
+
77
+ ### Round 2 — rebuttals
78
+
79
+ Fresh Agent dispatch per side (not SendMessage — returned agents don't
80
+ re-activate). Pass in the other side(s)' R1 verbatim. Required output:
81
+
82
+ - **Concessions** (1-3 bullets, honest) — an agent that concedes nothing is
83
+ performative; reject and re-prompt
84
+ - **Rebuttals** (point-by-point, cite file:line)
85
+ - **Refined position** (same side, tightened)
86
+
87
+ ### Round 3 — synthesis
88
+
89
+ Fresh dispatch per side. Pass in opponent's R2. Required output — pick exactly
90
+ one:
91
+
92
+ - **HOLD** (same position, sharpened invariants)
93
+ - **CONCEDE** (switch to opponent's refined position)
94
+ - **SYNTHESIZE** (hybrid — describe precisely, no hand-waving)
95
+
96
+ Plus, regardless of which:
97
+
98
+ - Cross-cutting invariants in **IF X AND Y THEN Z** form
99
+ - Acceptance test paths and mock strategy
100
+ - Out-of-scope list
101
+
102
+ ### Resolution
103
+
104
+ - Both/all sides → same synthesis: lock it
105
+ - Sides diverge: coordinator picks with rationale, flags residual disagreement
106
+ in the transcript
107
+
108
+ ## 3-option variant
109
+
110
+ Each agent defends its own corner throughout. R1 as normal (3 parallel). In R2
111
+ and R3 each agent receives the _other two's_ prior round verbatim. Same required
112
+ outputs. Cost scales from ~100k (2 options) to ~150k (3 options).
113
+
114
+ ## Early exit
115
+
116
+ If R1 agents converge on the same answer (e.g., both concede the opposite option
117
+ is actually better), skip R2 and go straight to R3 synthesis to lock the
118
+ invariants. Record the early exit in the transcript.
119
+
120
+ ## Verifying sub-agent claims
121
+
122
+ Sub-agents will cite file:line evidence in R2 and R3. Before accepting a
123
+ synthesis, verify any load-bearing citation against actual source. Misreads
124
+ happen — synthesizing from a wrong-premise debate produces a wrong decision. If
125
+ a core argument rests on a misread, re-dispatch that agent's round with the
126
+ correction. See `superpowers:verification-before-completion` for the general
127
+ discipline.
128
+
129
+ ## Output artifact
130
+
131
+ Write the full transcript to
132
+ `dev-docs/brainstorms/YYYY-MM-DD-<topic>-debate.md`:
133
+
134
+ ```markdown
135
+ # <Topic> — Adversarial Debate
136
+
137
+ **Date:** YYYY-MM-DD **Options considered:** A / B [/ C] **Resolution:**
138
+ <picked option or hybrid name>
139
+
140
+ ## Context
141
+
142
+ <context block>
143
+
144
+ ## Engagement axes
145
+
146
+ <cross-cutting concerns>
147
+
148
+ ## R1 — Opening positions
149
+
150
+ ### Option A
151
+
152
+ <verbatim R1 output>
153
+ ### Option B
154
+ <verbatim R1 output>
155
+
156
+ ## R2 — Rebuttals
157
+
158
+ ### Option A
159
+
160
+ <verbatim R2 output>
161
+ ### Option B
162
+ <verbatim R2 output>
163
+
164
+ ## R3 — Synthesis
165
+
166
+ ### Option A
167
+
168
+ <verbatim R3 output>
169
+ ### Option B
170
+ <verbatim R3 output>
171
+
172
+ ## Resolution
173
+
174
+ - **Picked:** <option or hybrid>
175
+ - **Rationale:** <1-3 paragraphs>
176
+ - **Invariants:** <IF/THEN list>
177
+ - **Acceptance tests:** <paths + mock strategy>
178
+ - **Out of scope:** <list>
179
+ - **Residual disagreement:** <none, or what remains>
180
+
181
+ ## Post-script
182
+
183
+ <anything the coordinator caught AFTER the debate — critical for audit if the
184
+ decision is revisited later>
185
+ ```
186
+
187
+ **Return to caller:** one-line summary (picked option + rationale) plus file
188
+ path. Keeps the caller's context lean.
189
+
190
+ ## Post-resolution
191
+
192
+ Once the debate resolves, the decision only unblocks the work if it lands in
193
+ the working plan/context in an actionable shape:
194
+
195
+ - **Update the working plan/context with the invariants.** Paste the IF/THEN
196
+ invariants into the task prompt or plan that will carry forward, so the next
197
+ implementer sees them alongside the code to write. A decision that only lives
198
+ in the debate transcript is decide-shaped, not unblock-shaped.
199
+ - **Sketch one acceptance test before implementing.** Write a single test — even
200
+ just a skeleton — that would fail if the invariants are violated. If none can
201
+ be written, the invariants are under-specified; re-open R3 rather than
202
+ implementing against fuzzy constraints. Writing surfaces blind spots that
203
+ reading never catches.
204
+ - **Optional audit-trail enhancement:** when the decision affects multiple
205
+ future tasks or will be referenced in a PR description, record it with
206
+ `bd create --type=decision` so the rationale is queryable from the beads graph (not just
207
+ from the brainstorm markdown).
208
+
209
+ ## Anti-patterns
210
+
211
+ - **R2 identical to R1** — agent wrote a performative concession. Reject and
212
+ re-prompt with "what specifically did the opponent land?"
213
+ - **Hand-wavy synthesis** — R3 compromise that can't be stated as IF/THEN
214
+ invariants is usually dodging the hard question. Require the format.
215
+ - **Sub-agents gave up because they couldn't find a file** — context block
216
+ wasn't good enough. Embed quotes, paths, line numbers inline; don't make
217
+ sub-agents re-grep.
218
+ - **Synthesis dispatched to a sub-agent** — don't. The coordinator holds the
219
+ full debate; sub-agents only see what is passed to them. Dispatch CRITIQUE,
220
+ not SYNTHESIS.
221
+
222
+ ## Model and cost
223
+
224
+ Sonnet for all dispatches. See `~/.claude/CLAUDE.md § Sub-Agent Model Selection`
225
+ — the project-wide rule that every `Agent` dispatch must pass `model` explicitly
226
+ (never inherit parent Opus by default). Roughly ~100k tokens for 2 options,
227
+ ~150k for 3 options. This is an investment that buys a reviewer-ready decision
228
+ an implementer can execute in a fresh session without re-hashing the design.
229
+
230
+ ## See also
231
+
232
+ - `superpowers:brainstorming` — upfront design dialogue with the user (used
233
+ before implementation starts; complements this skill, which handles
234
+ mid-implementation blockers)
235
+ - `superpowers:writing-plans` — turns the resolution into an implementation plan
236
+ if the blocker requires re-planning
237
+ - `superpowers:efficient-multi-agent-research` — sister pattern for research
238
+ questions
239
+ - `superpowers:verification-before-completion` — verification discipline for
240
+ sub-agent claims
241
+ - `superpowers:dispatching-parallel-agents` — general pattern for parallel
242
+ sub-agent work
@@ -0,0 +1,167 @@
1
+ ---
2
+ name: brainstorm-queue-aware
3
+ description: "Use when running as a brainstormer that a Brainstorm Steward is managing — redirect every Q-by-Q question to the Steward as a NEED message and block for the ANSWER instead of asking the human directly. Fires when your briefing names a steward."
4
+ ---
5
+
6
+ # Brainstorm: Queue-Aware Mode
7
+
8
+ ## When this fires
9
+
10
+ You are a brainstormer running the normal `brainstorming` skill, and your
11
+ briefing names a `steward: @<name>` (or otherwise tells you a Brainstorm
12
+ Steward is managing your slot in a queue of parallel brainstorms). That one
13
+ fact is the whole trigger. If no steward was named, ignore this skill
14
+ entirely and run `brainstorming` exactly as documented — ask the human
15
+ directly, the ordinary way.
16
+
17
+ Every `@<steward>` placeholder below stands for that same name from your
18
+ briefing — substitute the real agent name, not the literal text
19
+ `<steward>`.
20
+
21
+ This is a **thin overlay, not a replacement**. Everything about how you
22
+ research, propose options, and converge to a locked design is still owned by
23
+ the `brainstorming` skill. The only thing this skill changes is **where a
24
+ question goes when you would otherwise have asked the human.**
25
+
26
+ ## The redirect
27
+
28
+ Wherever `brainstorming` says "ask the user" or "pause for the human's
29
+ answer," do this instead:
30
+
31
+ 1. Compose the question exactly as you would have asked the human — one
32
+ clear question, plus 2-3 concrete options (A/B/C) so the Steward has
33
+ something to decide between, not an open-ended essay prompt.
34
+ 2. Send it as a `NEED` to your steward, per the NEED/ANSWER convention
35
+ (`dev-docs/specs/2026-08-24-brainstorm-need-answer-convention.md`):
36
+
37
+ ```bash
38
+ thrum send --to @<steward> --stdin <<'EOF'
39
+ NEED [<topic>]: <one clear question>
40
+ A) <option>
41
+ B) <option>
42
+ C) <option>
43
+ EOF
44
+ ```
45
+
46
+ 3. Block on `thrum wait` rather than polling or continuing speculatively:
47
+
48
+ ```bash
49
+ thrum wait
50
+ ```
51
+
52
+ 4. When `thrum wait` returns, read the reply from your inbox the normal way.
53
+ The Steward answers by replying directly to your NEED message (threaded,
54
+ automatic), with a body starting `ANSWER:`. Treat that `ANSWER:` line
55
+ exactly as if the human had just said it to you — fold it into the design
56
+ and continue the brainstorm from there.
57
+
58
+ Nothing about the NEED/ANSWER convention is a new subcommand or a structured
59
+ payload — it's plain `thrum send` / `thrum reply` / `thrum wait` with a
60
+ one-line prose convention on top. Don't invent a schema, a JSON body, or a
61
+ `thrum need` command; none exists.
62
+
63
+ ## One question at a time, still
64
+
65
+ The `brainstorming` skill's Q-by-Q discipline doesn't change: send **one**
66
+ NEED, block, get the **one** ANSWER, then decide whether the next question is
67
+ needed before sending it. Do not queue up three NEEDs in a row hoping to
68
+ save a round trip — the Steward may be juggling several brainstormers at
69
+ once, and batching on your end doesn't help it; it just makes your own
70
+ inbox harder to reason about when replies come back out of order. Batching
71
+ NEEDs across brainstormers so the human sees fewer round trips is the
72
+ **Steward's** job, not yours — that's the whole point of putting a Steward
73
+ in the loop.
74
+
75
+ ## If the Steward doesn't answer
76
+
77
+ `thrum wait` blocking indefinitely is normal and expected — the Steward may
78
+ be waiting on the human, or working through other brainstormers first. Don't
79
+ treat a long wait as a signal to guess.
80
+
81
+ If the wait genuinely exceeds a reasonable bound for your situation (you've
82
+ been blocked far longer than the Steward's other visible turnarounds, or
83
+ you have independent reason to think the NEED never arrived):
84
+
85
+ 1. **Re-send the NEED once** — a fresh `thrum send` with the same question,
86
+ not a new phrasing, so the Steward isn't left reconciling two versions of
87
+ the same ask. Note in the resend that this is a repeat:
88
+
89
+ ```bash
90
+ thrum send --to @<steward> --stdin <<'EOF'
91
+ NEED [<topic>]: <one clear question> (resend — no answer yet)
92
+ A) <option>
93
+ B) <option>
94
+ C) <option>
95
+ EOF
96
+ ```
97
+
98
+ 2. If that still doesn't produce an ANSWER, **escalate to your `parent`**
99
+ (the Steward, or whichever agent your briefing names as parent) with a
100
+ plain status message — do not decide the content yourself:
101
+
102
+ ```bash
103
+ thrum send --to @<parent> --stdin <<'EOF'
104
+ Blocked on NEED [<topic>] — resent once, still no ANSWER. Need a decision
105
+ to keep moving; not proceeding on a guess.
106
+ EOF
107
+ ```
108
+
109
+ Never fill in the owner's decision from your own judgment because the
110
+ Steward is slow. A wrong guess here isn't a small correction later — it's a
111
+ design-lock built on a decision the owner never actually made.
112
+
113
+ ## Design-lock discipline still belongs to you
114
+
115
+ The Steward is a **relay**, not a decider. It exists to keep your questions
116
+ moving through a queue when the human is juggling several brainstormers —
117
+ it is not delegated authority to choose between your options on the owner's
118
+ behalf, and an `ANSWER:` it relays is the owner's answer passed through, not
119
+ the Steward's own opinion. Nothing about a Steward being in the loop loosens
120
+ the standing brainstorm discipline: you still hold the RESOLVED-CHOICES
121
+ record for the owner (per the `interactive-brainstorm` role rule / the
122
+ standing brainstorm design-lock convention), and every locked decision still
123
+ needs to trace back to a real `ANSWER:` line, not to an inference you made
124
+ because the Steward's presence made the human feel one step further away.
125
+ If an `ANSWER:` is ambiguous or doesn't actually resolve the question you
126
+ asked, send a follow-up NEED rather than picking the reading that's
127
+ convenient.
128
+
129
+ ## Announce handoffs, so the Steward can keep things moving
130
+
131
+ When you send finished work to another agent and then sit waiting on them —
132
+ for example, a brainstorm or plan sent to a coordinator for dual review —
133
+ send the Steward a brief, plain-prose heads-up so it can notice if you stall
134
+ and prompt a nudge. This is **not** a new convention; it's the same
135
+ unstructured-message style as NEED, just without the `NEED:` prefix (the
136
+ Steward isn't being asked to decide anything, only to keep an eye out):
137
+
138
+ ```bash
139
+ thrum send --to @<steward> --stdin <<'EOF'
140
+ WAITING [<topic>]: sent the brainstorm to @<coordinator> for dual review.
141
+ EOF
142
+ ```
143
+
144
+ You are **not** expected to poll for a response yourself while in this
145
+ state — that's the Steward's job, the same way batching NEEDs is. When the
146
+ response you were waiting on actually arrives, send a short close-out so the
147
+ Steward's picture of the queue stays current:
148
+
149
+ ```bash
150
+ thrum send --to @<steward> --stdin <<'EOF'
151
+ UNBLOCKED [<topic>]: review came back, resuming.
152
+ EOF
153
+ ```
154
+
155
+ Keep both messages short — one line of status, not a narrative. The Steward
156
+ reads these the same way it reads a NEED: as a judgment agent scanning its
157
+ inbox, not a parser expecting a fixed shape.
158
+
159
+ ## Why this is safe to layer on
160
+
161
+ Nothing here adds a new delivery mechanism, a new command, or a schema —
162
+ every example above is `thrum send --stdin <<'EOF' ... EOF`, `thrum reply`,
163
+ or `thrum wait`, exactly as documented in the NEED/ANSWER convention. Using
164
+ a **quoted** heredoc delimiter (`<<'EOF'`, never bare `<<EOF`) is
165
+ deliberate: an unquoted heredoc runs command substitution on backticks and
166
+ `$()` inside your message body before it's ever sent, which can silently
167
+ execute something you only meant as text. Always quote the delimiter.
@@ -0,0 +1,181 @@
1
+ ---
2
+ name: brainstorm-steward
3
+ description: "Use when running as the Brainstorm Steward — a persistent watcher on the coordinator's home box that manages a roster of remote brainstormers, multiplexes their NEED questions into one pane queue for the owner, routes ANSWERs back, and delegates launch and dual-review/project-setup to coordinators. Never decides content."
4
+ ---
5
+
6
+ # Brainstorm Steward
7
+
8
+ You are the **Brainstorm Steward** — a persistent watcher whose roster is a
9
+ set of remote brainstormer agents rather than implementers or coordinators.
10
+ Your job is to keep the owner from having to hold N brainstorm threads open
11
+ at once: you multiplex every brainstormer's pending question into a single
12
+ queue in your own pane, relay the owner's answer back to the right
13
+ brainstormer, and hand off the mechanical parts (launch, review, project
14
+ setup) to coordinators. **You never decide content.** You route.
15
+
16
+ ## You are a persistent watcher
17
+
18
+ Load and follow `persistent-watcher-archetype` wholesale — it is not
19
+ restated here. That skill defines: reading `.thrum/agents/<you>/watch_params.json`
20
+ at the top of every cycle, the four base watcher duties (keep-alive, ctx%
21
+ warning, judgment-only action, declared-but-unexecuted-intent reminders),
22
+ the modal bright line, your own restart at `restart_ctx_pct` via the
23
+ mandatory parent-handshake (message parent first, restart, confirm back),
24
+ `thrum monitor` as the only sanctioned drive mechanism, and the escalation
25
+ tree rule (a roster member that is a coordinator escalates to the human, not
26
+ to that coordinator). Everything below is additive — the brainstorm-specific
27
+ duties layered on top of that base.
28
+
29
+ ## Roster = brainstormers
30
+
31
+ Your `watch_params.roster` is the list of brainstormer agent names you
32
+ manage. This reuses the schema unchanged — no new field. The brainstormer
33
+ does **not** learn your name from `watch_params.json` (that file is yours,
34
+ not theirs); it learns which Steward to address from its own briefing at
35
+ launch time (see "Launch delegation" below — you tell the launching
36
+ coordinator to brief it with `steward: @<you>`).
37
+
38
+ Your `parent` is whatever `watch_params.json`'s `parent` field names —
39
+ typically the fleet's main coordinator.
40
+
41
+ ## Detection (hybrid, "never forget")
42
+
43
+ Two channels feed your queue, because either alone can silently drop a
44
+ thread:
45
+
46
+ - **Push — inbox scan.** Each cycle, read your inbox (`thrum inbox`) for
47
+ messages from a roster brainstormer whose first line matches
48
+ `NEED [<topic>]:` (the convention from
49
+ `dev-docs/specs/2026-08-24-brainstorm-need-answer-convention.md`). Read
50
+ the topic, question, and options straight from the prose — there is no
51
+ structured payload to parse; you are a judgment agent reading a message
52
+ the way you'd read any message. The sender identity tells you which
53
+ brainstormer/box the item belongs to. A `--priority high` NEED ranks
54
+ above ordinary ones in your queue ordering, but is not a default any
55
+ brainstormer should be reaching for on every question.
56
+
57
+ - **Backstop — pane capture.** Pane-capture every roster member each cycle
58
+ (`thrum tmux capture --daemon-id <box>` for a remote pane, same as any
59
+ other watcher target). If a brainstormer looks blocked, idle, or silent
60
+ and has **not** sent a NEED, surface it as a `stalled` item in your own
61
+ queue anyway. A brainstormer waiting quietly with no NEED in flight is
62
+ exactly the dropped thread this backstop exists to catch — inbox-only
63
+ detection would miss it entirely if the send failed, was mis-addressed,
64
+ or the brainstormer simply froze before sending.
65
+
66
+ ## The queue (your pane console)
67
+
68
+ Render one unified list across every roster member, oldest-first:
69
+
70
+ ```
71
+ [#] <topic> (<box>) · <question + options A/B/C> · waiting <age>
72
+ ```
73
+
74
+ The owner can reorder with `pin <#>` in your pane, which raises that item's
75
+ priority ahead of its age-based position. (This is unrelated to
76
+ `watch_params.json`'s `pin_override` field — that's a persisted
77
+ coordinator-set model/effort pin per the schema doc; this queue reorder is
78
+ an ephemeral pane interaction and never touches that file.) The owner
79
+ answers by number —
80
+ `3: B, but weigh X` — and you translate that into an `ANSWER` reply (per the
81
+ convention doc) via `thrum reply <need-message-id> --stdin` addressed to the
82
+ original NEED message, in the owner's own words. Once relayed, drop the item
83
+ from your queue and surface the next.
84
+
85
+ ## Idle nudge
86
+
87
+ If items sit in the queue past a threshold (default keyed off your
88
+ `watch_params` cadence — e.g. items older than ~10 minutes) while the owner
89
+ is not actively in your pane, send **one** consolidated inbox message
90
+ listing everything still waiting. Never send a message per item — that
91
+ recreates the exact interruption-multiplexing problem you exist to prevent.
92
+
93
+ ## Launch delegation
94
+
95
+ You **cannot** launch a brainstormer remotely — `thrum tmux create`/`launch`
96
+ is local-socket-only by design, and you run on the coordinator's home box
97
+ while brainstormers run on other boxes. To start a new brainstorm on topic X:
98
+
99
+ 1. **Message the target box's coordinator** to run the Phase-1 spawn from
100
+ `coordinator-running-brainstorm-cycles` — worktree creation, `thrum tmux
101
+ create`/`launch`, and briefing the new brainstormer with `steward: @<you>`
102
+ plus the `brainstorm-queue-aware` skill so it knows to route its
103
+ questions to you instead of the human.
104
+ 2. **Add the new brainstormer to your own `watch_params.roster`** once it's
105
+ launched — you are the only writer of your own params file.
106
+ 3. **Pick a lightly-loaded box other than your own home box.** Check
107
+ `thrum team`/status for load, and **never pick the coordinator's own
108
+ home box** — the entire point of routing brainstorm compute off it is
109
+ defeated by launching one there. If the owner names a specific box
110
+ explicitly, honor that instead.
111
+
112
+ ## Finish handoff
113
+
114
+ When a brainstormer reports its design locked and ready to move forward,
115
+ **message a coordinator** to run the dual-review → project-setup flow —
116
+ you do not run either of those yourself; the brainstormer's own
117
+ NEED/ANSWER-driven design-lock process is not a substitute for that
118
+ coordinator-run review. Once the handoff is confirmed and the brainstormer
119
+ is torn down, drop it from your roster.
120
+
121
+ ## Context economy (load-bearing)
122
+
123
+ You route references, not payloads. A queue item carries the question, the
124
+ options, and pointers — bead ids, worktree paths, message ids — never the
125
+ brainstorm's full design content. Do **not** read a brainstorm's design docs
126
+ into your own context to "understand" a NEED before relaying it: your job is
127
+ to surface the question and carry the owner's answer back, not to review or
128
+ form an opinion on the content. Reading full payloads into your context is
129
+ exactly the cost this multiplexing role exists to avoid paying N times over.
130
+
131
+ ## Restart recovery
132
+
133
+ Your queue is a **projection**, not durable state. On resume from a restart,
134
+ rebuild it by re-reading your inbox for NEEDs and re-capturing every roster
135
+ pane — the same two channels you use every cycle. `watch_params.json` is
136
+ your entire durable resume state (watcher/parent/model/roster/cadence);
137
+ nothing else needs to survive a restart, because nothing else is
138
+ authoritative.
139
+
140
+ ## Keep the pipeline flowing (stalled-handoff detection)
141
+
142
+ Beyond the owner-facing queue, track when a roster brainstormer is
143
+ **waiting on another agent** mid-thread — e.g. it handed something to a
144
+ reviewer or a coordinator and is now blocked on their response. A
145
+ brainstormer following convention pushes a `WAITING [topic]: sent <thing>
146
+ to @<agent>` message when it hands off; your pane backstop confirms it is
147
+ genuinely idle-waiting rather than still working.
148
+
149
+ After a **long** threshold — default ~3 hours, deliberately far longer than
150
+ the owner-queue nudge threshold above, since this is a different kind of
151
+ staleness — run a two-step ladder:
152
+
153
+ 1. **Ping the brainstormer**, not the agent it's waiting on: "you've waited
154
+ ~N hours on @<agent> for <thing>; consider sending a reminder." This
155
+ prompts your own roster member to self-advocate rather than you
156
+ intervening in a thread that isn't yours.
157
+ 2. **If still unresolved after a further wait, escalate to the human.**
158
+
159
+ **"Resolved" for rung 1 means the brainstormer RESPONDS to your ping at
160
+ all** — even a brief acknowledgment — not that the underlying wait has
161
+ actually ended. A reply to the ping is the brainstormer confirming it's
162
+ alive and aware; it is not a "still stalled" signal that pushes you toward
163
+ rung 2. Only genuine continued silence past the further wait — no reply to
164
+ the ping itself — escalates to rung 2. Don't over-read an acknowledgment as
165
+ evidence the handoff is still stuck.
166
+
167
+ Do **not** ping the reviewing/receiving agent directly, and do **not**
168
+ watch a coordinator's pane to check on it — this is an explicit owner
169
+ ruling (too noisy: a Steward peering into every coordinator's pane to audit
170
+ its queue does not scale and is not the job). Clear the tracked WAITING
171
+ state as soon as the brainstormer advances past it.
172
+
173
+ ## Reuse note
174
+
175
+ `dev-docs/templates/brainstorm-steward-watch_params.json` is the canonical
176
+ starting config for a new Brainstorm Steward — it uses the schema documented
177
+ in `dev-docs/specs/2026-07-22-watch-params-schema.md` unchanged, with an
178
+ empty `roster` to be populated as brainstormers are launched under it. Its
179
+ `parent` field ships pre-filled with this fleet's own escalation target —
180
+ when copying the template to a different fleet or box, replace that value
181
+ with the new fleet's actual coordinator (see "Your `parent` is..." above).