opencode-thrum-pro 0.1.5 → 0.1.6
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-_compact-runtime-commands.md +61 -0
- package/assets/commands/thrum-_snapshot-protocol.md +17 -6
- package/assets/commands/thrum-_stamp-protocol.md +9 -2
- package/assets/commands/thrum-compact-extended.md +352 -0
- package/assets/commands/thrum-compact.md +300 -0
- package/assets/commands/thrum-inbox.md +1 -1
- package/assets/commands/thrum-restart-extended.md +84 -11
- package/assets/commands/thrum-restart.md +105 -13
- package/assets/commands/thrum-send.md +4 -1
- package/assets/commands/thrum-sleep-extended.md +67 -46
- package/assets/commands/thrum-sleep.md +67 -58
- package/assets/skills/adversarial-critique/SKILL.md +5 -8
- package/assets/skills/brainstorm-steward/SKILL.md +65 -11
- package/assets/skills/brainstormer-staying-current/SKILL.md +1 -4
- package/assets/skills/choosing-subagent-models/SKILL.md +14 -0
- package/assets/skills/conversation-only-context/SKILL.md +11 -11
- package/assets/skills/conversation-only-context/resources/driver-subagent-pattern.md +1 -1
- package/assets/skills/conversation-only-context/resources/remote-environment-scenarios.md +1 -1
- package/assets/skills/coordinator-assessing-agent-completion/SKILL.md +98 -6
- package/assets/skills/coordinator-context-monitoring/SKILL.md +29 -19
- package/assets/skills/coordinator-deploying-a-node/SKILL.md +124 -0
- package/assets/skills/coordinator-dispatching-work/SKILL.md +24 -11
- package/assets/skills/coordinator-hotpath-merge-gate/SKILL.md +62 -20
- package/assets/skills/coordinator-managing-state-and-lifecycle/SKILL.md +6 -6
- package/assets/skills/coordinator-merging-code/SKILL.md +25 -11
- package/assets/skills/coordinator-philosophy-merge-gate/SKILL.md +28 -7
- package/assets/skills/coordinator-plan-reconcile-gate/SKILL.md +3 -3
- package/assets/skills/coordinator-rolling-out-to-nodes/SKILL.md +92 -0
- package/assets/skills/coordinator-running-autonomous-feature-development/SKILL.md +3 -3
- package/assets/skills/coordinator-running-brainstorm-cycles/SKILL.md +21 -20
- package/assets/skills/coordinator-running-review-cycles/SKILL.md +15 -4
- package/assets/skills/diagnosing-fleet-and-daemon/SKILL.md +0 -2
- package/assets/skills/efficient-multi-agent-research/SKILL.md +3 -3
- package/assets/skills/implementer-orchestrating-execution/SKILL.md +11 -14
- package/assets/skills/orchestrate/SKILL.md +47 -35
- package/assets/skills/persistent-watcher-archetype/SKILL.md +172 -25
- package/assets/skills/persistent-watcher-archetype/resources/capture_archive.py +618 -0
- package/assets/skills/persistent-watcher-archetype/resources/jev_watcher_filter.py +837 -0
- package/assets/skills/persistent-watcher-archetype/resources/roster-watch.sh +1140 -0
- package/assets/skills/persistent-watcher-archetype/resources/roster-watch_test.sh +291 -0
- package/assets/skills/persistent-watcher-archetype/resources/thrum-capture-fallback.sh +2 -2
- package/assets/skills/persistent-watcher-archetype/resources/thrum-watch-pane-capture.sh +20 -8
- package/assets/skills/prime-agent/SKILL.md +10 -0
- package/assets/skills/project-setup/SKILL.md +22 -16
- package/assets/skills/project-setup/resources/implementation-agent.md +56 -35
- package/assets/skills/researcher-investigating/SKILL.md +2 -5
- package/assets/skills/thrum/SKILL.md +14 -7
- package/assets/skills/thrum/resources/ANTI_PATTERNS.md +16 -18
- package/assets/skills/thrum/resources/CLI_REFERENCE.md +17 -11
- package/assets/skills/thrum/resources/LISTENER_PATTERN.md +9 -3
- package/assets/skills/thrum/resources/MESSAGING.md +18 -11
- package/assets/skills/thrum/resources/WORKTREES.md +1 -1
- package/assets/skills/thrum-memory/SKILL.md +1 -1
- package/assets/skills/trace-spec-to-plan/resources/sweep-agent-prompt.md +1 -1
- package/assets/skills/update-queue/SKILL.md +6 -8
- package/assets/skills/using-the-dashboard/SKILL.md +30 -0
- package/assets/skills/using-the-queue/SKILL.md +76 -5
- package/assets/skills/using-thrum-state/SKILL.md +83 -0
- package/assets/skills/verify-against-plan/SKILL.md +120 -5
- package/assets/skills/watcher-archetype/SKILL.md +18 -0
- package/assets/skills/writing-durable-markdown/SKILL.md +5 -0
- package/dist/installer.js +4 -4
- package/dist/permission-fixture.integration.test.js +4 -4
- package/package.json +1 -1
- package/assets/skills/coordinator-deploying-the-fleet/SKILL.md +0 -396
- package/dist/allowlist-sync.test.d.ts +0 -1
- package/dist/allowlist-sync.test.js +0 -44
|
@@ -90,9 +90,11 @@ merge target before merging.
|
|
|
90
90
|
|
|
91
91
|
## 3. PASS-3 GATES — DISPATCH BOTH TO THE GATE RUNNER
|
|
92
92
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
93
|
+
1. Select from your team of established long-running gate agents.
|
|
94
|
+
2. Choose an available pair for hot-path and philosophy.
|
|
95
|
+
3. Tell those agents where sensitive tests must execute.
|
|
96
|
+
4. Launch a new gate agent only if the persistent set is genuinely unavailable —
|
|
97
|
+
never merely because an old candidate-specific session is stale.
|
|
96
98
|
|
|
97
99
|
Record the dispatch on your own queue (`thrum queue assign <bundle>
|
|
98
100
|
<gate-runner>`) per `coordinator-dispatching-work`'s queue step before
|
|
@@ -157,7 +159,9 @@ worktree; its sub-agents get READ-ONLY git. `checkout`/`reset`/`restore`/`stash`
|
|
|
157
159
|
`clean`/`rebase` forbidden in **every** directory for both. Give an escape hatch
|
|
158
160
|
for instrument-and-undo (a `cp` copy, or edit-then-revert) or the careful agent
|
|
159
161
|
breaches the fence doing good work. **Use `rm -r`, NEVER `rm -rf`.**
|
|
160
|
-
**Pasting a fence is not enforcing it.**
|
|
162
|
+
**Pasting a fence is not enforcing it.** This same fenced commit capability is
|
|
163
|
+
what the sanctioned `GATE-AUTHORED` mechanical-bookkeeping-fix commit uses — it
|
|
164
|
+
is not a new permission grant.
|
|
161
165
|
|
|
162
166
|
## 4. THE EXECUTED VERIFY — SCOPED TO THE CHANGE
|
|
163
167
|
|
|
@@ -175,7 +179,13 @@ executed half is **scoped to the change**:
|
|
|
175
179
|
- The `merge-base --is-ancestor` fast-forward check (§6).
|
|
176
180
|
- Any `*_tripwire_test.go` the change touches must stay green or the diff must
|
|
177
181
|
state why its premise changed; a tripwire edited to accommodate the change is a
|
|
178
|
-
finding, not a fix
|
|
182
|
+
finding, not a fix — **except** a mechanical follow-up (updating a stale
|
|
183
|
+
expectation to merely track an already-landed, already-reviewed change: a
|
|
184
|
+
renumbered line, a regenerated census key, and the like), which the gate may
|
|
185
|
+
fix itself as a `GATE-AUTHORED` commit and re-run. A tripwire edit that changes
|
|
186
|
+
what the tripwire actually *enforces* — any design or behavior judgment call —
|
|
187
|
+
stays a finding, never a self-administered fix. Keep this distinction sharp;
|
|
188
|
+
it is the highest-risk edit in this whole sequence.
|
|
179
189
|
- 🔴 **The CLASS-firing governance gates, on the merged tree — they are BLIND to
|
|
180
190
|
changed-package scoping, exactly like the `//go:embed` asset in §5.**
|
|
181
191
|
`TestFixtureDriftGuard_NoUnlistedSchemaMirrors` (`internal/schema`) and
|
|
@@ -186,18 +196,18 @@ executed half is **scoped to the change**:
|
|
|
186
196
|
it every merge: `git diff <base> <tip> | grep -iE 'CREATE TABLE|ALTER TABLE|durablelane|MirrorWriter|sanctionedMirrorWriters'`
|
|
187
197
|
— ANY hit ⇒ also run `go test ./internal/schema/ -run TestFixtureDriftGuard` and
|
|
188
198
|
`go test ./tests/gate/ -run TestEveryMirrorWriterIsSanctioned` on the MERGED tree.
|
|
189
|
-
Measured
|
|
199
|
+
Measured previously: kgi7t (`TestEveryMirrorWriterIsSanctioned`) and xo58f
|
|
190
200
|
(`TestFixtureDriftGuard`) BOTH escaped per-merge Pass-3 this way and surfaced only
|
|
191
201
|
in the daily gate as trunk-reds. The changed-package rule below is necessary, not
|
|
192
202
|
sufficient — a class gate is a property of the TREE, not the neighbourhood.
|
|
193
203
|
🔴 **Also always-run, same class-gate reasoning:**
|
|
194
204
|
`TestNoMainStateDBWriteOwnerBypasses` (`internal/testgate`; corpus 5.1
|
|
195
205
|
owner-bypass-check) — a scanner ratchet over every raw main-State-DB write
|
|
196
|
-
site, blind to changed-package scoping the same way. Measured
|
|
197
|
-
|
|
206
|
+
site, blind to changed-package scoping the same way. Measured previously:
|
|
207
|
+
a merged branch introduced a raw `r.db.ExecContext` outside
|
|
198
208
|
`safedb.WriteCoordinator` in a durable-lane cold-boot restore step; the
|
|
199
209
|
ratchet went 213→214 and gate_thrum's Pass-3 on that merge was CLEAN because
|
|
200
|
-
this test was not yet in the always-run set
|
|
210
|
+
this test was not yet in the always-run set. Run it on the
|
|
201
211
|
MERGED tree every merge: `go test ./internal/testgate/... -run
|
|
202
212
|
TestNoMainStateDBWriteOwnerBypasses`.
|
|
203
213
|
|
|
@@ -272,12 +282,16 @@ agreeing (`rev-parse origin/<branch>` and `ls-remote`). **Assert the branch TIP*
|
|
|
272
282
|
1. **The verdict artifact.** The runner saves verdicts to
|
|
273
283
|
`dev-docs/gate-reports/<ISO-week>/<date>/<gate-slug>/` and **commits them
|
|
274
284
|
BEFORE removing any worktree.** Save → commit → then destroy. A verdict that
|
|
275
|
-
exists only in a message cannot be audited later.
|
|
285
|
+
exists only in a message cannot be audited later. The artifact must be able to
|
|
286
|
+
carry a `CLEAN-WITH-GATE-FIXES` outcome, and when one applies it cites the
|
|
287
|
+
`GATE-AUTHORED` commit SHA.
|
|
276
288
|
2. **The efficacy row**, in `dev-docs/hotpath-gate-efficacy.md` — required for
|
|
277
289
|
**every** trigger-dir merge, including `SKIPPED_WITH_EVIDENCE` rows and
|
|
278
290
|
orchestrator-run merges. The log measures gate **coverage**, not just outcomes.
|
|
279
291
|
Record `FALSE_POSITIVE=0` explicitly on a clean run so the zero is a
|
|
280
|
-
measurement rather than an absence.
|
|
292
|
+
measurement rather than an absence. Same rule applies here: an
|
|
293
|
+
`outcome=CLEAN-WITH-GATE-FIXES` row cites the `GATE-AUTHORED` commit SHA when
|
|
294
|
+
one exists.
|
|
281
295
|
3. **Commit accumulated agent state** under `.thrum/agents/` along with the merge.
|
|
282
296
|
Uncommitted agent state exists in exactly one working tree, and it IS the
|
|
283
297
|
agent's memory across restarts. **Never `git add -f`.**
|
|
@@ -90,6 +90,14 @@ dispatch time — hand this list verbatim:
|
|
|
90
90
|
carrying dupes instead of the real content.
|
|
91
91
|
6. Run full-package `-race`, not targeted `-run` — a targeted race run
|
|
92
92
|
misses cross-test races that only a full-package run surfaces.
|
|
93
|
+
**Exception: `internal/daemon/rpc` must NEVER be run monolithically** — a
|
|
94
|
+
bare `go test [-race] ./internal/daemon/rpc` cannot finish inside any
|
|
95
|
+
gate-length timeout. Run it through the sharded runner (`race-shard`,
|
|
96
|
+
`scripts/test-run.sh race ./internal/daemon/rpc`, or `make gate`) and confirm
|
|
97
|
+
the gate's output shows it executed. A bound-timeout with ZERO test failures
|
|
98
|
+
is a false red: classify it with `go run ./cmd/testgate classify-timeout
|
|
99
|
+
--log <file> --shard-config <file> --shard <name>` (only BOUND-TIMEOUT exits
|
|
100
|
+
0) before reporting a regression. See item 7 of `coordinator-hotpath-merge-gate`.
|
|
93
101
|
7. Build+test the MERGED-tree result as a SEPARATE condition — neither gate
|
|
94
102
|
currently runs a build of the actual post-merge tree; a clean pre-merge
|
|
95
103
|
build/test does not prove the merged result compiles or passes.
|
|
@@ -414,13 +422,26 @@ Two cautions, so this rule does not cause its own incident:
|
|
|
414
422
|
|
|
415
423
|
## If it fails
|
|
416
424
|
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
425
|
+
For a genuine anti-pattern, Lens 10 finding, production-behaviour issue, or
|
|
426
|
+
design judgment call: send it back as a normal review finding — same channel as
|
|
427
|
+
dual-review output, folded into the same numbered list if dual review is still
|
|
428
|
+
open, or as its own short reply if dual review already passed. Cite the
|
|
429
|
+
offending function/file and which anti-pattern (`ph<N>`), meta-check, or Lens
|
|
430
|
+
10 sub-probe it failed. Do NOT block on Lens 10d findings that are genuinely
|
|
431
|
+
disclaimed substrate issues (see Lens 10 scope discipline above); DO block on
|
|
432
|
+
any Lens 10b or 10d finding on NEW work.
|
|
433
|
+
|
|
434
|
+
For mechanical bookkeeping only (census/shard regen via the tool, line-number
|
|
435
|
+
or key refreshes, ledger totals/ceilings where the arithmetic is derivable, a
|
|
436
|
+
per-entry waiver or citation comment recording a classification already
|
|
437
|
+
established elsewhere (never a new safety judgment of your own), a nosec
|
|
438
|
+
baseline hash for an already-reviewed pattern, comment wording, stale test
|
|
439
|
+
expectations that merely follow a landed change): fix it yourself as a
|
|
440
|
+
`GATE-AUTHORED` commit on your
|
|
441
|
+
`gate/` branch, re-run ONLY the check(s) the fix affects, and report
|
|
442
|
+
`CLEAN-WITH-GATE-FIXES` listing each fix instead of bouncing it to the owner.
|
|
443
|
+
When unsure which bucket a finding falls in, ask the coordinator with the exact
|
|
444
|
+
diff — don't bounce reflexively.
|
|
424
445
|
|
|
425
446
|
## See also
|
|
426
447
|
|
|
@@ -67,11 +67,11 @@ Spawn **one** top-level agent, `model: "fable"`.
|
|
|
67
67
|
|
|
68
68
|
This is not a self-granted exception; it is the single deliberate use of
|
|
69
69
|
Fable anywhere in the system, kept as an independent check-and-balance
|
|
70
|
-
against everything else, which runs on the
|
|
70
|
+
against everything else, which runs on the standard tier ceiling (see `choosing-subagent-models`).
|
|
71
71
|
Fable — a distinct, more-capable model — is the right instrument specifically
|
|
72
72
|
because a holistic cross-plan reconcile (does seam X mean the same thing in
|
|
73
|
-
plan ① as in plan ②?) benefits from a different model than the
|
|
74
|
-
per-plan reviews, a form of cross-document judgment a
|
|
73
|
+
plan ① as in plan ②?) benefits from a different model than the standard-tier
|
|
74
|
+
per-plan reviews, a form of cross-document judgment a standard-tier pass has
|
|
75
75
|
been shown to miss.
|
|
76
76
|
|
|
77
77
|
This is the **one named, cited exception** to the standing "never SELECT
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: coordinator-rolling-out-to-nodes
|
|
3
|
+
description: "Use when rolling a build across all nodes — fleet deploy, rolling the nodes, deploy everywhere, ship to every node, canary then the rest, promote the canary, staged rollout, deploying after a merge batch. Orchestrates the staged order and the promotion gate between stages, and delegates each node to the coordinator-deploying-a-node runbook. Load this BEFORE dispatching any node."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Coordinator: Rolling Out a Build Across All Nodes — staged order, canary, promotion gate
|
|
7
|
+
|
|
8
|
+
> This skill is the ORCHESTRATION layer. It does not replace
|
|
9
|
+
> `coordinator-deploying-a-node` — it calls it, once per node.
|
|
10
|
+
|
|
11
|
+
## 0. Universal invariants (read first — these outrank everything below)
|
|
12
|
+
|
|
13
|
+
These hold for every deployment regardless of project or topology. The adapter supplies *how*, these define *what must be true*.
|
|
14
|
+
|
|
15
|
+
1. **Build once; distribute identical bytes.** One pinned immutable artifact (SHA/version/checksum triple) is built once at one SHA on the build host; every node installs from that same artifact. No node re-derives it. Pin exact SHA, never tip. Adapter: `fleet.deployment.thrum.artifact` or `fleet.deployment.products.<id>.artifact`.
|
|
16
|
+
2. **Target-local mutation.** The node-local coordinator performs the mutation (install/migrate/restart) locally on its own host. Never drive a node's build/install/restart from another host. The orchestrator dispatches and gates; the node executes.
|
|
17
|
+
3. **Immutable identifier + checksum.** Artifact is identified by SHA + version + checksum; verify BEFORE install that the delivered bundle is the one the orchestrator built. Adapter: `artifact.checksum`, `artifact.version_file`, `artifact.commit_file`.
|
|
18
|
+
4. **Canary evidence does not transfer.** A canary pass proves the *build* is sound; it does not prove any other node's *state* is sound. Every node takes its own BEFORE readings.
|
|
19
|
+
5. **Verify by observed effect, never exit code.** Install/restart success is proven by post-mutation observation (version equals pin, NEW PID, service status reports pin, migration moved), not by installer exit 0. Adapter: `install.verify_by_effect`, `health.probes`.
|
|
20
|
+
6. **Capture before/after.** For every node, capture BEFORE state (current version/state, health counters) before mutation and AFTER state after; compare.
|
|
21
|
+
7. **Account for every target.** Roster completeness: enumerate topology from config, disposition each node (rolled on pin / deferred with owner sign-off + notify local coordinator), and never normalize unmeasured rows.
|
|
22
|
+
|
|
23
|
+
Additional parameterized invariants (skill-owned, adapter-valued):
|
|
24
|
+
|
|
25
|
+
- Pull-current first (ff-only) before reasoning about state. Adapter: `preflight.pull_command`.
|
|
26
|
+
- Backup before touching anything; sizing via adapter formula. Adapter: `backup.command`, `backup.sizing_formula`.
|
|
27
|
+
- Never bypass the storage engine's file ownership. Adapter: `storage_access.via`, `storage_access.forbidden`.
|
|
28
|
+
- Install-before-restart ordering; re-render between install and restart. Adapter: `templates.order`.
|
|
29
|
+
- Convergence wait from mechanism, not impatience. Adapter: `health.convergence_wait`.
|
|
30
|
+
|
|
31
|
+
## 1. Enumerate topology (from adapter — never hard-code)
|
|
32
|
+
|
|
33
|
+
Read the project's deployment adapter inside `.thrum/config.json` (`fleet.deployment`; human-readable reference at the deployment-adapter reference). Never hard-code topology or commands in the dispatch or in this skill — read them from that single source.
|
|
34
|
+
|
|
35
|
+
- For Thrum fleet plus connected daemons: `fleet.deployment.thrum.topology` (`canary`, `waves`, `excluded`, `connected_daemons`, `identity_resolution`).
|
|
36
|
+
- For a customer product `<id>`: `fleet.deployment.products.<id>.topology` (same shape, per-product `canary`/`nodes`/`waves`).
|
|
37
|
+
|
|
38
|
+
Resolve each node's `daemon_id` / `ssh_alias` / `coordinator` via the adapter's `identity_resolution` method (daemon_id join, not name). If topology is empty, STOP — do not invent nodes.
|
|
39
|
+
|
|
40
|
+
**Why every node carries an `ssh_alias`:** so the rolling coordinator can reach the node directly when the messaging or pane-mirror path fails. The main case is an agent stuck on a permission prompt or dialog. Read the pane with `ssh <alias> tmux capture-pane -p -t <session>`, then answer a prompt you recognise as safe with `tmux send-keys`. Never approve blindly, and never pick a "don't ask again" option. Re-capture afterwards to confirm the pane moved on. A node flagged `blocked-on-human` gets unblocked this way in the same turn; don't wait on it or reorder the roll around it. The alias is for pane interaction and artifact distribution only. The node still builds, installs and restarts itself, through its own coordinator.
|
|
41
|
+
|
|
42
|
+
> Example — Thrum project: topology canary and waves are defined in `topology.canary` / `topology.waves` (seven boxes, one excluded), connected daemons per `topology.connected_daemons`. Build host and build command are adapter values, not skill literals.
|
|
43
|
+
|
|
44
|
+
## 2. Pin the artifact (build once at SHA/version/checksum)
|
|
45
|
+
|
|
46
|
+
Derive the immutable pin on the build host (adapter `artifact.build_host`): current `HEAD` SHA, version, and checksum. When multiple related artifacts (e.g., core plus connected-repo bundles) are involved, pin each immutably and distribute the same set to every relevant node. Announce the pin in the dispatch so every node can verify it.
|
|
47
|
+
|
|
48
|
+
Artifact identity lives in `artifact.output`, `artifact.version_file`, `artifact.commit_file`, `artifact.checksum`. Never use a floating tag like tip; always the pinned SHA.
|
|
49
|
+
|
|
50
|
+
## 3. Preflight (control-plane current, forward-only, backup sizing via adapter)
|
|
51
|
+
|
|
52
|
+
- Verify control-plane checkout is current: `preflight.pull_command` (must be ff-only; if not fast-forwardable, STOP and surface).
|
|
53
|
+
- Forward-only check per node: `preflight.forward_only_check` — prove the pin is an ancestor of the node's current SHA (plus a control that must FAIL, e.g., an invented SHA, to prove the check discriminates).
|
|
54
|
+
- Backup sizing via adapter: `backup.sizing_formula` — compute `free_at_completion` per the formula before running `backup.command`; if the projected peak exceeds the safe threshold, STOP and escalate.
|
|
55
|
+
|
|
56
|
+
## 4. Build once → distribute identical artifact (mechanism via adapter)
|
|
57
|
+
|
|
58
|
+
Build once per artifact on its `artifact.build_host` via `artifact.build_command` → verify the produced bundle's version/checksum/commit sidecar → distribute the identical bytes to every node's inbound drop path (`artifact.distribution.drop_path`) via the adapter's `artifact.distribution.mechanisms` (e.g., drop-folder or copy). No node re-derives or rebuilds. Verify BEFORE unpack that the delivered bundle matches the pin.
|
|
59
|
+
|
|
60
|
+
> Example — Thrum project: build once via the adapter's `artifact.build_command` on the adapter's `artifact.build_host`, distribute via the adapter's `artifact.distribution.mechanisms` to `artifact.distribution.drop_path`, bundle carries sidecars verified per adapter.
|
|
61
|
+
|
|
62
|
+
## 5. The staged order — canary, waves, prepare-and-hold, promotion gate
|
|
63
|
+
|
|
64
|
+
- **Canary first, alone.** One node (adapter `topology.canary`) rolls first. Its health must be observed green before any wave proceeds.
|
|
65
|
+
- **Waves with coordinated dependency/order/rollback.** Subsequent waves follow `topology.waves`. When related daemons share ordering (e.g., connected-repo daemons that must restart together), respect the adapter-defined dependency and restart order; a failure in one dependent daemon triggers coordinated rollback per adapter `rollback` / `backup.restore_command`.
|
|
66
|
+
- **Prepare-and-hold + release BY NAME.** If the mechanism supports it, prepare all nodes in a wave (acquire + verify artifact, take BEFORE snapshot, but do not restart) then release by explicit node name, not by broadcast.
|
|
67
|
+
- **Promotion gate.** After each stage, verify by observed effect on that node (see node skill) before promoting. On no-go, halt the rollout and roll back the affected node(s) per adapter.
|
|
68
|
+
|
|
69
|
+
## 6. Dispatching a node — what the message must carry
|
|
70
|
+
|
|
71
|
+
Dispatch each node to its own local coordinator (resolved via `identity_resolution`), never via remote shell for the mutation itself. The dispatch message must carry:
|
|
72
|
+
|
|
73
|
+
- Pinned artifact identifier (SHA/version/checksum) and drop-path location.
|
|
74
|
+
- Which adapter section to use (`fleet.deployment.thrum` vs `fleet.deployment.products.<id>`).
|
|
75
|
+
- Expected pin for verification and the BEFORE-snapshot request.
|
|
76
|
+
- Hold/release semantics if using prepare-and-hold.
|
|
77
|
+
|
|
78
|
+
The node's local runbook is `coordinator-deploying-a-node` — reference that skill by name in the dispatch.
|
|
79
|
+
|
|
80
|
+
## 7. After the last node — roster completeness, phase reconciliation, test gate
|
|
81
|
+
|
|
82
|
+
- Enumerate the topology again from the same adapter source and disposition every entry (rolled on pin / deferred with owner sign-off + notify local coordinator). Missing or unmeasured rows are not normalized.
|
|
83
|
+
- Reconcile registry/phase: verify every daemon reports the pin (adapter `health.probes` + `install.verify_by_effect`), and that agent phases have converged.
|
|
84
|
+
- Run the project's gate that is appropriate for the change (e.g., `make gate` or equivalent) before declaring success.
|
|
85
|
+
|
|
86
|
+
## 8. Holds and red flags
|
|
87
|
+
|
|
88
|
+
- If `fleet.deployment` is absent or `fleet.deployment.products` and `fleet.deployment.thrum` are both empty, STOP — no topology is defined.
|
|
89
|
+
- If the control-plane pull is not fast-forwardable, STOP.
|
|
90
|
+
- If `fleet.deployment.thrum.products` exists (vestigial), STOP — products live only at `fleet.deployment.products`.
|
|
91
|
+
- If a node reports success by exit code alone without observed-effect verification, treat as not-verified.
|
|
92
|
+
- Never wrap a service restart in a blind timeout on the node (see node skill `service.never_timeout` and `migration.signal_rules`).
|
|
@@ -106,8 +106,8 @@ outlive its author and later be enforced as if it were the human's mandate.
|
|
|
106
106
|
through a standing orchestrator.**
|
|
107
107
|
|
|
108
108
|
The reason, in one line: orchestrators own the implementer lifecycle and the
|
|
109
|
-
`--model
|
|
110
|
-
|
|
109
|
+
`--model` pin (from `runtime.role_models`, per `choosing-subagent-models`); standing one up yourself risks the implementer inheriting
|
|
110
|
+
your own model. Your lane is dispatch-decision + gate + merge. Full dispatch mechanics
|
|
111
111
|
live in **`coordinator-dispatching-work`**.
|
|
112
112
|
|
|
113
113
|
**Recovery:** if an implementer was ever stood up directly, **tear it down
|
|
@@ -117,7 +117,7 @@ coordinator-spawned implementer — it may carry the wrong model.
|
|
|
117
117
|
| Rationalization | Reality |
|
|
118
118
|
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
119
119
|
| "I'll just stand up the implementer myself, it's faster." | **WRONG** — route through a standing orchestrator. |
|
|
120
|
-
| "The orchestrator can just adopt the implementer I already spawned." | **WRONG** — it may carry
|
|
120
|
+
| "The orchestrator can just adopt the implementer I already spawned." | **WRONG** — it may carry a costly model. Tear it down first; let the orchestrator spawn its own with the pinned model. |
|
|
121
121
|
|
|
122
122
|
## Coordinator-run Q&A vs escalate
|
|
123
123
|
|
|
@@ -40,7 +40,7 @@ at every stage:
|
|
|
40
40
|
the impl prompt** → 8. Hand off to coord for implementer dispatch.
|
|
41
41
|
|
|
42
42
|
**Three explicit review gates** at stages 3, 6, and 7 — same dual-axis pattern
|
|
43
|
-
each time (`verify-against-source` + a prose-quality reviewer,
|
|
43
|
+
each time (`verify-against-source` + a prose-quality reviewer, sub-agents (model per `choosing-subagent-models`)
|
|
44
44
|
in parallel — see "Review-loop mechanics" below). Skipping any review gate is a
|
|
45
45
|
documented anti-pattern. The brainstorm review catches design issues; the plan
|
|
46
46
|
review is the SOLE quality gate on the plan doc — the researcher authors the
|
|
@@ -50,16 +50,13 @@ implementer executes against them.
|
|
|
50
50
|
|
|
51
51
|
## Subagent model selection
|
|
52
52
|
|
|
53
|
-
> **Model tiers:** pass an explicit `model:` on every dispatch
|
|
54
|
-
> (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
|
|
55
|
-
> operator-ask or a skill step that names it. See the
|
|
56
|
-
> `choosing-subagent-models` skill for the full policy.
|
|
53
|
+
> **Model tiers:** pass an explicit `model:` on every dispatch; choose model and effort per the `choosing-subagent-models` skill (read `runtime.role_models` at the moment of use). Never let a sub-agent inherit your own model.
|
|
57
54
|
|
|
58
55
|
### Prefer `efficient-multi-agent-research` for multi-part research
|
|
59
56
|
|
|
60
57
|
When a research or investigation task has independent parts, reach for the
|
|
61
58
|
`efficient-multi-agent-research` skill FIRST — it partitions the work across
|
|
62
|
-
many cheap parallel subagents (
|
|
59
|
+
many cheap parallel subagents (cheap gatherers, judgment-tier synthesizers) instead of
|
|
63
60
|
one expensive serial subagent. It is the preferred research path: cheaper,
|
|
64
61
|
faster, and it keeps each subagent's context tight.
|
|
65
62
|
|
|
@@ -73,9 +70,9 @@ names only its stage-specific source.
|
|
|
73
70
|
| Axis | Reviewer | Notes |
|
|
74
71
|
| --------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
75
72
|
| **Conformance** | `verify-against-source` (thrum-owned skill) | Does the artifact honor its INPUT(s)? Replaces `verify-against-plan` at prose gates — `verify-against-plan` BAILS without a code diff + a File-Structure table, so it cannot run on a brainstorm/plan/prompt. `verify-against-source` accepts a prose artifact + source doc with neither. |
|
|
76
|
-
| **Quality** | general-purpose
|
|
73
|
+
| **Quality** | general-purpose sub-agent (model per `choosing-subagent-models`) + prose-quality rubric (PRIMARY) ∥ `superpowers:requesting-code-review` (SUPPLEMENTARY) | The general-purpose prose-quality pass (internal consistency, gaps, contradiction, ambiguity, scope creep) is AUTHORITATIVE. `requesting-code-review` runs on a DIFF, so point it at the artifact's own commit range (`HEAD~1..HEAD`) — gated on the skill being resolvable; skip gracefully if absent. ⚠️ **That is the diff of the `.md` file, NOT a diff against the production code the artifact describes** — this row does NOT cover the code axis. Prose-vs-code is Conformance's job (see `verify-against-source` § "Second comparison unit"). |
|
|
77
74
|
|
|
78
|
-
Both are `general-purpose`, `model:
|
|
75
|
+
Both are `general-purpose`, `model: <per choosing-subagent-models>`, `run_in_background: true`. Wait
|
|
79
76
|
for BOTH before consolidating. Verify each BLOCKING against source before
|
|
80
77
|
forwarding.
|
|
81
78
|
|
|
@@ -158,7 +155,7 @@ external skill — the researcher writes both artifacts directly, governed by
|
|
|
158
155
|
this skill's own protocol block (Phase 2) and structure/stamp/deviations
|
|
159
156
|
requirements (Phase 6). There is nothing to pre-flight-check or bail on for
|
|
160
157
|
either stage, and no `/plugin install` path: no such plugin is declared
|
|
161
|
-
anywhere in this repo's `.claude-plugin/marketplace.json
|
|
158
|
+
anywhere in this repo's `.claude-plugin/marketplace.json`.
|
|
162
159
|
|
|
163
160
|
The one genuinely optional external supplement is `requesting-code-review`
|
|
164
161
|
(Review-loop mechanics, "Quality" row) — not resolvable → SKIP the
|
|
@@ -226,7 +223,7 @@ noise — start fresh.
|
|
|
226
223
|
|
|
227
224
|
| Topic shape | Base branch |
|
|
228
225
|
| ------------------------------------------------------------------------------------ | ----------------------------------------------------- |
|
|
229
|
-
| Bug fix, hardening, infra cleanup belonging to the current line | The configured merge target — `jq -r '.orchestration.merge_target'
|
|
226
|
+
| Bug fix, hardening, infra cleanup belonging to the current line | The configured merge target — `CONFIG=.thrum/config.json; [ -f .thrum/redirect ] && CONFIG="$(cat .thrum/redirect)/config.json"; jq -r '.orchestration.merge_target' "$CONFIG"` (a worktree's `.thrum/` holds only a `redirect` file, not its own `config.json`) |
|
|
230
227
|
| Work belonging to a multi-epic version program | The version's long-lived branch |
|
|
231
228
|
| Work tied to an existing feature epic with its own long-lived branch | That branch |
|
|
232
229
|
|
|
@@ -397,7 +394,7 @@ When the researcher reports the brainstorm is ready for review, run the
|
|
|
397
394
|
SUPPLEMENTARY (internal consistency, technical soundness, anti-patterns,
|
|
398
395
|
gaps).
|
|
399
396
|
|
|
400
|
-
Both `general-purpose`, `model:
|
|
397
|
+
Both `general-purpose`, `model: <per choosing-subagent-models>`, `run_in_background: true`. **Have the
|
|
401
398
|
researcher append the gate footer and commit (in their own worktree) BEFORE you
|
|
402
399
|
spawn the dual-review sub-agents** — the brainstorm lives in the researcher's
|
|
403
400
|
branch, and the supplementary `requesting-code-review` pass needs a real
|
|
@@ -422,7 +419,7 @@ confidence about what's already correct and prevents over-editing.
|
|
|
422
419
|
|
|
423
420
|
When the researcher reports their fixes are done:
|
|
424
421
|
|
|
425
|
-
- Run a **targeted verification sub-agent** (one sub-agent,
|
|
422
|
+
- Run a **targeted verification sub-agent** (one sub-agent, model per `choosing-subagent-models`) that reads
|
|
426
423
|
the updated doc and confirms each prescribed fix landed correctly. Do NOT
|
|
427
424
|
re-derive the original findings — that's done.
|
|
428
425
|
- For tiny cosmetic fixes (one-line format updates, missing citations), ask
|
|
@@ -440,10 +437,10 @@ to merge" with stand-down instructions.
|
|
|
440
437
|
## Phase 5 — Overarching coherence pass (when sibling brainstorms close)
|
|
441
438
|
|
|
442
439
|
If the topic is part of a larger program with multiple parallel brainstorms,
|
|
443
|
-
once **all sibling brainstorms reach ready-to-merge**, fire
|
|
444
|
-
coherence + implementability pass over the corpus before specs are written.
|
|
440
|
+
once **all sibling brainstorms reach ready-to-merge**, fire a deep-review
|
|
441
|
+
(model per `choosing-subagent-models`) coherence + implementability pass over the corpus before specs are written.
|
|
445
442
|
|
|
446
|
-
Two parallel passes (background,
|
|
443
|
+
Two parallel passes (background, a deeper tier per `choosing-subagent-models` — escalate because this
|
|
447
444
|
is genuinely cross-cutting reasoning over a large corpus):
|
|
448
445
|
|
|
449
446
|
| Pass | Focus |
|
|
@@ -609,10 +606,14 @@ review it before dispatch.
|
|
|
609
606
|
misread cited code or stretch citations. Spot-verify any BLOCKING that names a
|
|
610
607
|
specific file/line/symbol before forwarding.
|
|
611
608
|
|
|
612
|
-
❌ **`thrum message read --all` mid-brainstorm
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
609
|
+
❌ **`thrum message read --all --force` mid-brainstorm without checking the
|
|
610
|
+
report.** `--all` alone is a dry run (marks nothing); `--force` only drains
|
|
611
|
+
what THAT dry-run listing named, and reports any later arrival as excluded
|
|
612
|
+
rather than silently sweeping it in — so the old "B arrives
|
|
613
|
+
mid-read and gets silently marked" timing bomb no longer applies. Still
|
|
614
|
+
prefer `thrum message read <id> [<id>...]` with specific IDs when juggling
|
|
615
|
+
multiple researchers — it's simpler to reason about than tracking a listing's
|
|
616
|
+
10-minute validity window.
|
|
616
617
|
|
|
617
618
|
❌ **Sub-agents into the researcher's worktree.**
|
|
618
619
|
For code research in the brainstorm worktree, ask the researcher; for broader
|
|
@@ -621,7 +622,7 @@ the worktree path.
|
|
|
621
622
|
|
|
622
623
|
❌ **Skipping the coherence pass.** When ≥ 3 sibling brainstorms close in the
|
|
623
624
|
same program, integration-layer issues that no single review can see are
|
|
624
|
-
virtually guaranteed. Fire the
|
|
625
|
+
virtually guaranteed. Fire the deep-review pass; it's worth the cost.
|
|
625
626
|
|
|
626
627
|
❌ **Renaming brainstorm researchers between topics.** Identity is bound to the
|
|
627
628
|
worktree. If a topic is done, kill the tmux session and tear down the worktree;
|
|
@@ -17,10 +17,7 @@ they're independent reads of the same diff.
|
|
|
17
17
|
reviewers as parallel sub-agents in the same message. Pass each a clear scope
|
|
18
18
|
("review the diff at <BASE>...<HEAD> for <criteria>").
|
|
19
19
|
|
|
20
|
-
> **Model tiers:** pass an explicit `model:` on every dispatch
|
|
21
|
-
> (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
|
|
22
|
-
> operator-ask or a skill step that names it. See the
|
|
23
|
-
> `choosing-subagent-models` skill for the full policy.
|
|
20
|
+
> **Model tiers:** pass an explicit `model:` on every dispatch; choose model and effort per the `choosing-subagent-models` skill (read `runtime.role_models` at the moment of use). Never let a sub-agent inherit your own model.
|
|
24
21
|
|
|
25
22
|
## Wait for both reviewers before sending anything to the implementer
|
|
26
23
|
|
|
@@ -48,6 +45,20 @@ one.
|
|
|
48
45
|
when re-reviewing fixes, refer to "finding #4" and the implementer can locate
|
|
49
46
|
it instantly.
|
|
50
47
|
|
|
48
|
+
**Route mechanical bookkeeping findings to the gate, not the implementer.** If a
|
|
49
|
+
consolidated finding is itself mechanical bookkeeping of the kind the gate is
|
|
50
|
+
authorized to self-fix (see `coordinator-merging-code`: census/shard regen, line-
|
|
51
|
+
number or key refreshes, ledger totals/ceilings, per-entry waivers or citations
|
|
52
|
+
recording a classification already established elsewhere — never a new safety
|
|
53
|
+
judgment of your own — nosec baseline hashes, comment wording, stale test
|
|
54
|
+
expectations that merely follow a landed change), do not route it to the
|
|
55
|
+
implementer as a normal finding. Dual review runs BEFORE the Pass-3 gate, so at
|
|
56
|
+
this point there is no gate run yet to fix it: tag the finding as
|
|
57
|
+
gate-deferred-bookkeeping in the consolidated list and carry it forward — the
|
|
58
|
+
gate self-fixes it (a `GATE-AUTHORED` commit plus a narrow re-run of only the
|
|
59
|
+
affected checks) when it runs Pass-3 on this branch. Reserve immediate
|
|
60
|
+
implementer round-trips for real defects and design judgment calls.
|
|
61
|
+
|
|
51
62
|
## Verify reviewer claims against actual code before forwarding
|
|
52
63
|
|
|
53
64
|
**Why:** Reviewers reading a large diff sometimes cite wrong line numbers or
|
|
@@ -195,8 +195,6 @@ hypothesis confirmed.**
|
|
|
195
195
|
| Line | Meaning |
|
|
196
196
|
|---|---|
|
|
197
197
|
| `sync.apply: M1 relay loop detected … dropped` | Working as designed — loop suppression. |
|
|
198
|
-
| `storagegw: gossip: peer … not connected` | Peer offline. Routine. |
|
|
199
|
-
| `storagegw: gossip: peer call failed … caller-peer lacks required capability` | **NOT routine** — a live capability gap. Worth a bead if sustained. |
|
|
200
198
|
| `dead_agent_sweeper: marked dead agent offline` | Routine sweeper work. |
|
|
201
199
|
|
|
202
200
|
---
|
|
@@ -95,13 +95,13 @@ See the `choosing-subagent-models` skill for the full policy. Applied to this
|
|
|
95
95
|
skill's fan-out:
|
|
96
96
|
|
|
97
97
|
- **Level 1 — researchers / gatherers:** scope each one DOWN to a narrow slice
|
|
98
|
-
so you can run MANY in parallel. Use `model:
|
|
98
|
+
so you can run MANY in parallel. Use `model: <per choosing-subagent-models>` (cheapest tier) —
|
|
99
99
|
bounded gather-and-report. Smaller scope = cheaper, concurrent (faster),
|
|
100
100
|
tighter per-agent context.
|
|
101
|
-
- **Level 2 / Level 3 — summarizers / synthesizers:** use `model:
|
|
101
|
+
- **Level 2 / Level 3 — summarizers / synthesizers:** use `model: <per choosing-subagent-models>` —
|
|
102
102
|
aggregating and reconciling Level-1 outputs is judgment work.
|
|
103
103
|
|
|
104
|
-
Prefer many narrow
|
|
104
|
+
Prefer many narrow cheap gatherers over one broad subagent. This is the cheap,
|
|
105
105
|
fast default — equivalent parallelism at a fraction of the token cost.
|
|
106
106
|
|
|
107
107
|
## Common Mistakes
|
|
@@ -6,7 +6,7 @@ description: "Use when starting execution of a scoped implementation task — ab
|
|
|
6
6
|
# Implementer: Orchestrating Execution
|
|
7
7
|
|
|
8
8
|
You implement by **orchestrating sub-agents**, not by doing research, edits, and
|
|
9
|
-
verification yourself. Your
|
|
9
|
+
verification yourself. Your own context is for judgment — synthesizing
|
|
10
10
|
research, targeting edits, judging verification against the plan. The legwork
|
|
11
11
|
goes to cheaper sub-agents. This skill is the procedure; invoke it at the start
|
|
12
12
|
of executing any scoped task.
|
|
@@ -27,10 +27,7 @@ The size bound (~15 lines / 2 files) is the project default; a project-local
|
|
|
27
27
|
|
|
28
28
|
## Subagent model selection
|
|
29
29
|
|
|
30
|
-
> **Model tiers:** pass an explicit `model:` on every dispatch
|
|
31
|
-
> (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
|
|
32
|
-
> operator-ask or a skill step that names it. See the
|
|
33
|
-
> `choosing-subagent-models` skill for the full policy.
|
|
30
|
+
> **Model tiers:** pass an explicit `model:` on every dispatch; choose model and effort per the `choosing-subagent-models` skill (read `runtime.role_models` at the moment of use). Never let a sub-agent inherit your own model.
|
|
34
31
|
|
|
35
32
|
## Step 1 — Dispatch research
|
|
36
33
|
|
|
@@ -44,13 +41,13 @@ you do not read the code into your own context. Label the dispatch
|
|
|
44
41
|
From the report, decide exactly what changes where, then dispatch
|
|
45
42
|
general-purpose sub-agent(s) to make the edits. Give each the bd task ID, the
|
|
46
43
|
exact files, the acceptance criteria, and the relevant slice of the report.
|
|
47
|
-
Model: `
|
|
44
|
+
Model: per `choosing-subagent-models`; use the cheapest tier for purely mechanical edits
|
|
48
45
|
(find/replace, rename). Label `description="implement: <what>"`. Parallelize independent
|
|
49
46
|
edit-targets; serialize edits to shared files.
|
|
50
47
|
|
|
51
48
|
## Step 3 — Dispatch verification
|
|
52
49
|
|
|
53
|
-
Spawn a `
|
|
50
|
+
Spawn a verifier sub-agent (model per `choosing-subagent-models`) against **the plan the implementation sub-agent was
|
|
54
51
|
given** — does the diff satisfy the acceptance criteria and honor the plan?
|
|
55
52
|
Label `description="verify: <what>"`. (For the full code-quality +
|
|
56
53
|
spec-compliance review at DONE, `implementer-tdd-and-quality` and the
|
|
@@ -89,12 +86,12 @@ hard size bound.
|
|
|
89
86
|
|
|
90
87
|
| Dispatch | Model |
|
|
91
88
|
| ------------------ | -------------------------------------------------- |
|
|
92
|
-
| research / explore | `
|
|
93
|
-
| implementation | `
|
|
94
|
-
| verification | `
|
|
89
|
+
| research / explore | per `choosing-subagent-models` (or the `Explore` agent type) |
|
|
90
|
+
| implementation | per `choosing-subagent-models`; cheapest tier for purely mechanical edits |
|
|
91
|
+
| verification | per `choosing-subagent-models` |
|
|
95
92
|
|
|
96
|
-
Use the bare
|
|
97
|
-
|
|
93
|
+
Use the bare alias from `runtime.role_models`; do not hard-pin a version id.
|
|
94
|
+
Never let a sub-agent inherit the parent model.
|
|
98
95
|
|
|
99
96
|
## Sub-agent label convention (required)
|
|
100
97
|
|
|
@@ -105,8 +102,8 @@ delegation shape from these labels.
|
|
|
105
102
|
## Anti-patterns
|
|
106
103
|
|
|
107
104
|
❌ **Inline Worker** — does the research and edits itself instead of
|
|
108
|
-
dispatching. Your
|
|
109
|
-
edits a
|
|
105
|
+
dispatching. Your own context is for orchestration judgment, not hand-typing
|
|
106
|
+
edits a sub-agent should make.
|
|
110
107
|
|
|
111
108
|
❌ **Over-orchestrator** — dispatches a sub-agent for a known one-line change,
|
|
112
109
|
paying more in prompt-composition than the edit costs. The Step-0 scoping gate
|