@amsterdamdatalabs/enact-extensions 0.1.27 → 0.1.30
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.
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cmux-leader
|
|
3
|
+
description: "Become the cmux LEADER — spawn, brief, poll, unblock, and verify up to 5 parallel claude follower terminals in one cmux workspace. Use when orchestrating multi-session work across sibling terminals, driving followers, or coordinating parallel agents. Followers message back via the cmux-send skill."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# cmux-leader — you are the LEADER
|
|
7
|
+
|
|
8
|
+
You are a Claude Code session running **inside a cmux workspace**. You act as the
|
|
9
|
+
**leader/orchestrator**: you spawn, brief, poll, unblock, and verify **follower** claude sessions
|
|
10
|
+
running in sibling terminals of the same workspace. You coordinate; followers do the hands-on work.
|
|
11
|
+
|
|
12
|
+
## Hard rules
|
|
13
|
+
|
|
14
|
+
- **Terminal surfaces only.** Followers are `claude` running in a **terminal** surface. `agent-session`
|
|
15
|
+
surfaces (`new-surface --type agent-session`) are NOT scriptable — `send` / `read-screen` fail on them
|
|
16
|
+
with `Surface is not a terminal`. Always launch followers as `claude` in a terminal.
|
|
17
|
+
- **Max 5 parallel claude sessions**, all **horizontal splits** in **one** workspace.
|
|
18
|
+
- **Start each follower from the directory its work lives in** — so enact-context warms the right repo
|
|
19
|
+
(`enact-context: ON` must print on that session's shell start).
|
|
20
|
+
- **Lead from a NEUTRAL parent dir** (e.g. the common parent of all repos). The enact-loop **Stop hook
|
|
21
|
+
resolves the active loop by SHELL cwd** — if you `cd` into a follower's repo you inherit that loop's
|
|
22
|
+
Stop boulder and it blocks YOUR exit. To inspect a follower's repo use `git -C <path> …` /
|
|
23
|
+
absolute paths; **never `cd` into a follower repo.**
|
|
24
|
+
- **You orchestrate, you don't do the followers' work.** Assign → poll → unblock → verify. Keep your own
|
|
25
|
+
context for the plan and the merge/verification gates.
|
|
26
|
+
- One leader per workspace. If another session is already leading, don't fight it — coordinate.
|
|
27
|
+
|
|
28
|
+
## Orient first (always run these)
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
cmux current-window # which window
|
|
32
|
+
cmux workspace list # workspaces (this leader's is [selected])
|
|
33
|
+
cmux list-panes # panes in the workspace
|
|
34
|
+
cmux list-pane-surfaces # surfaces (sessions) in the focused pane
|
|
35
|
+
cmux list-pane-surfaces --pane pane:N # surfaces in a specific pane
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Identify each surface by name (e.g. `FOLLOWER-enact-wiki`). A surface you can `read-screen` is a
|
|
39
|
+
terminal session you can drive. Re-discover topology each session — never hardcode surface numbers.
|
|
40
|
+
|
|
41
|
+
## Read a follower
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
cmux read-screen --surface surface:N --lines 40 # tail of the live screen
|
|
45
|
+
cmux read-screen --surface surface:N --scrollback # full scrollback
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**In every follower briefing, tell the follower to use the `cmux-send` skill** for all replies — the
|
|
49
|
+
`[from] to [to]` envelope and the send→verify→enter submit protocol. A follower that doesn't know
|
|
50
|
+
cmux-send will park half-formed messages and break the relay.
|
|
51
|
+
|
|
52
|
+
## Drive a follower (see the cmux-send skill for the full messaging protocol)
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
cmux send --surface surface:N "your prompt here\n" # \n = Enter
|
|
56
|
+
cmux read-screen --surface surface:N --lines 12 # VERIFY it submitted
|
|
57
|
+
cmux send-key --surface surface:N enter # if it parked in the ❯ box (booting/thinking)
|
|
58
|
+
cmux send-key --surface surface:N ctrl+c # interrupt a runaway follower
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
**Always `read-screen` after every `send`** to confirm it landed. If still in the `❯` box, follow with
|
|
62
|
+
`send-key … enter` — NOT `ctrl+b`. `ctrl+b` only flushes a *queued* message when the follower has a
|
|
63
|
+
**running bash command** to background; while it is purely thinking, `ctrl+b` does nothing — just wait.
|
|
64
|
+
|
|
65
|
+
## Spawn a new follower (horizontal split, rooted in the work dir)
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
cmux new-split right --focus false # -> "OK surface:N pane:M ..."
|
|
69
|
+
cmux send --surface surface:N "cd /abs/path/to/repo && claude\n"
|
|
70
|
+
cmux read-screen --surface surface:N --lines 20 # confirm boot
|
|
71
|
+
cmux send --surface surface:N "You are a FOLLOWER under the cmux leader. <role + task>.\n"
|
|
72
|
+
cmux send-key --surface surface:N enter # Enter explicitly (it was booting)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
One-shot terminal with an explicit cwd (no `cd` needed):
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
cmux new-surface --type terminal --working-directory /abs/path/to/repo --pane pane:M --focus false
|
|
79
|
+
cmux send --surface surface:N "claude\n"
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Keep all splits horizontal; stop at 5 claude sessions total.
|
|
83
|
+
|
|
84
|
+
## Leader loop
|
|
85
|
+
|
|
86
|
+
1. **Plan & shard.** Break the goal into independent slices, one per follower (≤5). Pick each slice's
|
|
87
|
+
repo/dir so enact-context warms the right context.
|
|
88
|
+
2. **Spawn & brief.** Split → `cd <dir> && claude` → send a self-contained briefing (role, scope,
|
|
89
|
+
exit criteria, "report back in one line when done/blocked") using the cmux-send envelope.
|
|
90
|
+
3. **Poll.** Round-robin `read-screen` each follower. Watch for: finished, blocked, asking a question,
|
|
91
|
+
or idle at the `❯` prompt.
|
|
92
|
+
4. **Unblock.** Answer questions / re-scope via `send`. Never reach into a follower's repo yourself
|
|
93
|
+
unless you're the session that owns it.
|
|
94
|
+
5. **Verify & gate.** When a follower claims done, verify against real output (tests, build, PR state)
|
|
95
|
+
before you treat the slice as green. Don't accept self-reported green.
|
|
96
|
+
6. **Close.** Summarize across followers; drive the merge / final gate from the leader.
|
|
97
|
+
|
|
98
|
+
## Standing watch — poll every ~15 min, never go idle while followers run
|
|
99
|
+
|
|
100
|
+
A follower that finishes its task goes **idle at the `❯` prompt** — from the leader's seat that looks
|
|
101
|
+
identical to "stalled." `done` ≠ `handled`. If you go idle too, every lane stops and the user sees a
|
|
102
|
+
stalled board. Keep a **~15-minute poll cadence** for as long as any follower is live:
|
|
103
|
+
|
|
104
|
+
1. **(Re)discover topology first** — `cmux list-pane-surfaces [--pane pane:N]`. Never assume surface
|
|
105
|
+
numbers held across turns; they renumber.
|
|
106
|
+
2. **`read-screen` every follower** and classify each: *working* · *idle-done* · *parked message in the
|
|
107
|
+
`❯` box* · *blocked / asking* · *ctx ≥ 80% (needs `/compact`)*.
|
|
108
|
+
3. **Act per state:** idle-done → assign the next work package or explicitly park it · parked → `send-key
|
|
109
|
+
enter` · blocked/asking → answer · ctx ≥ 80% → tell it to `/compact` then resume.
|
|
110
|
+
4. **Report deltas to the user**, then schedule the next poll ~15 min out (e.g. via the `loop` skill or a
|
|
111
|
+
self-scheduled wake-up). Idle followers are wasted parallelism — the poll is how you keep all lanes fed.
|
|
112
|
+
|
|
113
|
+
## Quick reference (verified surface)
|
|
114
|
+
|
|
115
|
+
| Need | Command |
|
|
116
|
+
|---|---|
|
|
117
|
+
| List sessions | `cmux list-pane-surfaces [--pane pane:N]` |
|
|
118
|
+
| Read a session | `cmux read-screen --surface surface:N --lines 40` |
|
|
119
|
+
| Send + submit | `cmux send --surface surface:N "text\n"` |
|
|
120
|
+
| Submit a parked msg | `cmux send-key --surface surface:N enter` |
|
|
121
|
+
| Flush a queued msg (only if a command is running) | `cmux send-key --surface surface:N ctrl+b` |
|
|
122
|
+
| Interrupt | `cmux send-key --surface surface:N ctrl+c` |
|
|
123
|
+
| New right split | `cmux new-split right --focus false` |
|
|
124
|
+
| Terminal w/ cwd | `cmux new-surface --type terminal --working-directory <path> --pane pane:N` |
|
|
125
|
+
| Focus a pane | `cmux focus-pane --pane pane:N` |
|
|
126
|
+
|
|
127
|
+
Gotchas: agent-session ≠ scriptable (terminal only) · `\n` may not submit during boot/thinking (use
|
|
128
|
+
`send-key enter`) · `read-screen` takes `--surface`, not `--pane` · a `send` to a busy follower queues
|
|
129
|
+
and delivers at turn-end — `ctrl+b` flushes it **only if a command is running** · leader must not `cd`
|
|
130
|
+
into a follower repo (Stop-hook boulder capture — use `git -C`).
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cmux-send
|
|
3
|
+
description: "How to correctly send a message to a cmux follower surface — the send→verify→enter protocol and the [from] to [to] message envelope. Use whenever messaging a cmux session (leader→follower or follower→leader)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# cmux-send — message a cmux surface correctly
|
|
7
|
+
|
|
8
|
+
Sending a cmux message has two parts that are easy to get wrong: **submitting** it, and **wrapping** it.
|
|
9
|
+
|
|
10
|
+
## 1. Submit protocol (always verify the Enter landed)
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
cmux send --surface surface:N "<one-line message>\n" # \n = Enter
|
|
14
|
+
cmux read-screen --surface surface:N --lines 12 # VERIFY it submitted
|
|
15
|
+
# If the text is still sitting in the `❯` box (not submitted):
|
|
16
|
+
cmux send-key --surface surface:N enter
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- **Always `read-screen` after `send`.** A `\n` may NOT submit if the follower was booting or thinking —
|
|
20
|
+
the text parks in the `❯` box.
|
|
21
|
+
- **To submit a parked message, use `send-key … enter` — NOT `ctrl+b`.** `ctrl+b` only flushes a
|
|
22
|
+
*queued* message when the follower has a **running bash command** to background; on an idle or
|
|
23
|
+
purely-thinking follower it does nothing.
|
|
24
|
+
- **One line only.** Every literal `\n` submits, so a multi-line prompt fires early and fragments.
|
|
25
|
+
Compose the whole message on a single line; the trailing `\n` is the only submit.
|
|
26
|
+
- `read-screen` takes `--surface`, not `--pane`.
|
|
27
|
+
|
|
28
|
+
## 2. Message envelope (every message)
|
|
29
|
+
|
|
30
|
+
- **Start with:** `[<from-surface-name>] to [<to-surface-name>] `
|
|
31
|
+
- **End with:** `Respond back once you are done with using prefix "[<to-surface-name>] to [<from-surface-name>] "`
|
|
32
|
+
|
|
33
|
+
Surface names are the human labels (e.g. `LEADER`, `FOLLOWER-enact-wiki`), not `surface:N`. Map them with
|
|
34
|
+
`cmux list-pane-surfaces [--pane pane:N]`.
|
|
35
|
+
|
|
36
|
+
### Example (leader → follower)
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
cmux send --surface surface:3 "[LEADER] to [FOLLOWER-enact-wiki] <instruction on one line>. Respond back once you are done with using prefix \"[FOLLOWER-enact-wiki] to [LEADER] \"\n"
|
|
40
|
+
cmux read-screen --surface surface:3 --lines 12
|
|
41
|
+
# still in the ❯ box? -> cmux send-key --surface surface:3 enter
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Quick reference
|
|
45
|
+
|
|
46
|
+
| Need | Command |
|
|
47
|
+
|---|---|
|
|
48
|
+
| Send + submit | `cmux send --surface surface:N "text\n"` |
|
|
49
|
+
| Verify it landed | `cmux read-screen --surface surface:N --lines 12` |
|
|
50
|
+
| Submit a parked message | `cmux send-key --surface surface:N enter` |
|
|
51
|
+
| Flush a QUEUED msg (only if a command is running) | `cmux send-key --surface surface:N ctrl+b` |
|
|
52
|
+
| Interrupt a runaway | `cmux send-key --surface surface:N ctrl+c` |
|