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.
- package/assets/commands/thrum-_deviations-protocol.md +87 -0
- package/assets/commands/thrum-_generator-idempotency-protocol.md +15 -0
- package/assets/commands/thrum-_project-rules-protocol.md +18 -0
- package/assets/commands/thrum-_snapshot-protocol.md +265 -0
- package/assets/commands/thrum-_stamp-protocol.md +112 -0
- package/assets/commands/thrum-_verify-before-write-protocol.md +27 -0
- package/assets/commands/thrum-inbox.md +22 -0
- package/assets/commands/thrum-load-context.md +17 -0
- package/assets/commands/thrum-overview.md +17 -0
- package/assets/commands/thrum-prime.md +30 -0
- package/assets/commands/thrum-quickstart.md +14 -0
- package/assets/commands/thrum-reply.md +28 -0
- package/assets/commands/thrum-restart-extended.md +195 -0
- package/assets/commands/thrum-restart.md +293 -0
- package/assets/commands/thrum-send.md +31 -0
- package/assets/commands/thrum-sleep-extended.md +186 -0
- package/assets/commands/thrum-sleep.md +212 -0
- package/assets/commands/thrum-team.md +12 -0
- package/assets/commands/thrum-update-project.md +259 -0
- package/assets/commands/thrum-wait.md +14 -0
- package/assets/skills/adversarial-critique/SKILL.md +242 -0
- package/assets/skills/brainstorm-queue-aware/SKILL.md +167 -0
- package/assets/skills/brainstorm-steward/SKILL.md +181 -0
- package/assets/skills/choosing-subagent-models/SKILL.md +244 -0
- package/assets/skills/closing-findings-while-warm/SKILL.md +104 -0
- package/assets/skills/configure-roles/SKILL.md +229 -0
- package/assets/skills/coordinator-assessing-agent-completion/SKILL.md +205 -0
- package/assets/skills/coordinator-assessing-agent-completion/scan.py +117 -0
- package/assets/skills/coordinator-branch-split-on-block/SKILL.md +168 -0
- package/assets/skills/coordinator-context-monitoring/SKILL.md +674 -0
- package/assets/skills/coordinator-dispatching-work/SKILL.md +288 -0
- package/assets/skills/coordinator-hotpath-merge-gate/SKILL.md +522 -0
- package/assets/skills/coordinator-interacting-with-the-owner/SKILL.md +171 -0
- package/assets/skills/coordinator-maintaining-memory/SKILL.md +89 -0
- package/assets/skills/coordinator-managing-state-and-lifecycle/SKILL.md +192 -0
- package/assets/skills/coordinator-merging-code/SKILL.md +331 -0
- package/assets/skills/coordinator-philosophy-merge-gate/SKILL.md +442 -0
- package/assets/skills/coordinator-plan-reconcile-gate/SKILL.md +198 -0
- package/assets/skills/coordinator-post-restart-sweep/SKILL.md +135 -0
- package/assets/skills/coordinator-running-autonomous-feature-development/SKILL.md +199 -0
- package/assets/skills/coordinator-running-brainstorm-cycles/SKILL.md +654 -0
- package/assets/skills/coordinator-running-review-cycles/SKILL.md +153 -0
- package/assets/skills/coordinator-single-responsibility-merge-gate/SKILL.md +14 -0
- package/assets/skills/diagnosing-fleet-and-daemon/SKILL.md +255 -0
- package/assets/skills/efficient-multi-agent-research/SKILL.md +177 -0
- package/assets/skills/fixing-documentation-errors/SKILL.md +258 -0
- package/assets/skills/implementer-maintaining-memory/SKILL.md +84 -0
- package/assets/skills/implementer-orchestrating-execution/SKILL.md +125 -0
- package/assets/skills/implementer-receiving-dispatch/SKILL.md +127 -0
- package/assets/skills/implementer-receiving-review-feedback/SKILL.md +125 -0
- package/assets/skills/implementer-status-and-handoff/SKILL.md +150 -0
- package/assets/skills/implementer-tdd-and-quality/SKILL.md +99 -0
- package/assets/skills/memory-audit-recover/SKILL.md +153 -0
- package/assets/skills/memory-curate/SKILL.md +139 -0
- package/assets/skills/memory-maintenance/SKILL.md +87 -0
- package/assets/skills/memory-read-discipline/SKILL.md +164 -0
- package/assets/skills/memory-search-advanced/SKILL.md +217 -0
- package/assets/skills/memory-write-discipline/SKILL.md +135 -0
- package/assets/skills/orchestrate/SKILL.md +795 -0
- package/assets/skills/persistent-watcher-archetype/SKILL.md +225 -0
- package/assets/skills/prime-agent/SKILL.md +92 -0
- package/assets/skills/project-hotpath-gate/SKILL.md +255 -0
- package/assets/skills/project-philosophy/SKILL.md +418 -0
- package/assets/skills/project-philosophy/resources/philosophy-template.md +155 -0
- package/assets/skills/project-philosophy/resources/reliability-class-library.md +653 -0
- package/assets/skills/project-setup/SKILL.md +1007 -0
- package/assets/skills/project-setup/resources/implementation-agent.md +826 -0
- package/assets/skills/researcher-answering-queries/SKILL.md +100 -0
- package/assets/skills/researcher-investigating/SKILL.md +152 -0
- package/assets/skills/researcher-maintaining-memory/SKILL.md +176 -0
- package/assets/skills/state-migration/SKILL.md +54 -0
- package/assets/skills/thrum/SKILL.md +161 -0
- package/assets/skills/thrum/resources/ANTI_PATTERNS.md +132 -0
- package/assets/skills/thrum/resources/BOUNDARIES.md +56 -0
- package/assets/skills/thrum/resources/CLI_REFERENCE.md +1066 -0
- package/assets/skills/thrum/resources/IDENTITY.md +49 -0
- package/assets/skills/thrum/resources/LISTENER_PATTERN.md +64 -0
- package/assets/skills/thrum/resources/MESSAGING.md +163 -0
- package/assets/skills/thrum/resources/TMUX_SESSIONS.md +118 -0
- package/assets/skills/thrum/resources/WORKTREES.md +117 -0
- package/assets/skills/thrum-memory/SKILL.md +138 -0
- package/assets/skills/trace-spec-to-plan/SKILL.md +104 -0
- package/assets/skills/trace-spec-to-plan/resources/sweep-agent-prompt.md +57 -0
- package/assets/skills/update-queue/SKILL.md +149 -0
- package/assets/skills/using-the-queue/SKILL.md +172 -0
- package/assets/skills/using-thrum-state/SKILL.md +104 -0
- package/assets/skills/verify-against-plan/SKILL.md +323 -0
- package/assets/skills/verify-against-source/SKILL.md +237 -0
- package/assets/skills/watcher-archetype/SKILL.md +84 -0
- package/assets/skills/writing-durable-markdown/SKILL.md +66 -0
- package/dist/hooks/block-sync-cd.d.ts +9 -0
- package/dist/hooks/block-sync-cd.js +71 -0
- package/dist/hooks/block-sync-cd.test.d.ts +1 -0
- package/dist/hooks/block-sync-cd.test.js +61 -0
- package/dist/hooks/shell-env.d.ts +8 -0
- package/dist/hooks/shell-env.js +22 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +25 -0
- package/dist/installer.d.ts +2 -0
- package/dist/installer.js +86 -0
- 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).
|