@amsterdamdatalabs/enact-extensions 0.1.26 → 0.1.28
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,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mined-investigate-loop
|
|
3
|
+
description: >-
|
|
4
|
+
Auto-mined procedure (enact-evolve P4 procedural tier). Before editing
|
|
5
|
+
unfamiliar code, run an investigate loop: read a file, grep to locate the
|
|
6
|
+
related symbol/usage, then read the located target — read → grep → read —
|
|
7
|
+
before making changes. Mined from 251 real Claude+Codex sessions; sessions
|
|
8
|
+
that ran this loop succeeded at 58.3% vs a 43.0% baseline (+15pp). Use when
|
|
9
|
+
navigating unfamiliar code, locating a definition/usage, or scoping a change
|
|
10
|
+
before editing. Trigger keywords: investigate, locate, find usages, where is,
|
|
11
|
+
scope a change, read before edit, navigate code.
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# mined-investigate-loop (read → grep → read)
|
|
15
|
+
|
|
16
|
+
> **Provenance — machine-mined, pending human graduation (Track B G2).** This
|
|
17
|
+
> skill was produced by the enact-evolve procedural tier's execution-mining →
|
|
18
|
+
> graduation path over real session history. It is under review; do not treat it
|
|
19
|
+
> as hand-authored guidance until merged.
|
|
20
|
+
|
|
21
|
+
## The procedure
|
|
22
|
+
|
|
23
|
+
When you are about to change code you don't already hold in context, **investigate
|
|
24
|
+
before you act**:
|
|
25
|
+
|
|
26
|
+
1. **read** — open the entry file you were handed (the symbol, the failing test,
|
|
27
|
+
the reported file).
|
|
28
|
+
2. **grep** — search the repo for the related symbol / call site / definition you
|
|
29
|
+
now know to look for (don't guess the path; locate it).
|
|
30
|
+
3. **read** — open the located target and confirm the real shape before editing.
|
|
31
|
+
|
|
32
|
+
Only then edit. The loop may repeat (read → grep → read → grep → …) until the
|
|
33
|
+
change is fully scoped.
|
|
34
|
+
|
|
35
|
+
## When to use
|
|
36
|
+
|
|
37
|
+
- Navigating unfamiliar code or a new package.
|
|
38
|
+
- Locating a definition, its usages, or the blast radius of a change.
|
|
39
|
+
- Scoping an edit before making it (especially across files).
|
|
40
|
+
|
|
41
|
+
## When NOT to use
|
|
42
|
+
|
|
43
|
+
- You already have the target file and its dependencies in context — skip
|
|
44
|
+
straight to the edit.
|
|
45
|
+
- Pure debugging-thrash (grep → stream-edit → grep with no reads) is an
|
|
46
|
+
**anti-pattern** the miner explicitly rejected (see Evidence) — investigate by
|
|
47
|
+
reading, don't blind-edit-and-re-grep.
|
|
48
|
+
|
|
49
|
+
## Evidence (why this graduated)
|
|
50
|
+
|
|
51
|
+
Mined by `enact-evolve/eval/mine-procedures.mjs` over real session transcripts
|
|
52
|
+
(the existing Claude + Codex adapters → `SessionEvidence.tool_timeline`):
|
|
53
|
+
|
|
54
|
+
| field | value |
|
|
55
|
+
|---|---|
|
|
56
|
+
| corpus | 251 sessions (205 Claude + 46 Codex) |
|
|
57
|
+
| baseline zero-failure rate | 0.430 |
|
|
58
|
+
| this procedure (read → grep → read) | **60 sessions, 35 success → 0.583** |
|
|
59
|
+
| lift over baseline | **+0.153 (×1.36)** |
|
|
60
|
+
| graduation policy | rate ≥ 1.25× baseline, support ≥ 8, success ≥ 4 |
|
|
61
|
+
|
|
62
|
+
Reward signal: a session "succeeds" when it records zero failed tool/hook/watchdog
|
|
63
|
+
events (`SessionEvidence.failures` empty). Graduation is **lift-based** because the
|
|
64
|
+
absolute zero-failure base rate is low; frequency alone is rejected — the
|
|
65
|
+
highest-frequency pattern `rg → sed → rg` (debugging thrash) scored 2/13 (0.15)
|
|
66
|
+
and did **not** graduate.
|
|
67
|
+
|
|
68
|
+
Full artifact: `enact-evolve/eval/P4-mined-procedures.json`.
|
|
@@ -0,0 +1,111 @@
|
|
|
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
|
+
## Drive a follower (see the cmux-send skill for the full messaging protocol)
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
cmux send --surface surface:N "your prompt here\n" # \n = Enter
|
|
52
|
+
cmux read-screen --surface surface:N --lines 12 # VERIFY it submitted
|
|
53
|
+
cmux send-key --surface surface:N enter # if it parked in the ❯ box (booting/thinking)
|
|
54
|
+
cmux send-key --surface surface:N ctrl+c # interrupt a runaway follower
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
**Always `read-screen` after every `send`** to confirm it landed. If still in the `❯` box, follow with
|
|
58
|
+
`send-key … enter` — NOT `ctrl+b`. `ctrl+b` only flushes a *queued* message when the follower has a
|
|
59
|
+
**running bash command** to background; while it is purely thinking, `ctrl+b` does nothing — just wait.
|
|
60
|
+
|
|
61
|
+
## Spawn a new follower (horizontal split, rooted in the work dir)
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
cmux new-split right --focus false # -> "OK surface:N pane:M ..."
|
|
65
|
+
cmux send --surface surface:N "cd /abs/path/to/repo && claude\n"
|
|
66
|
+
cmux read-screen --surface surface:N --lines 20 # confirm boot
|
|
67
|
+
cmux send --surface surface:N "You are a FOLLOWER under the cmux leader. <role + task>.\n"
|
|
68
|
+
cmux send-key --surface surface:N enter # Enter explicitly (it was booting)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
One-shot terminal with an explicit cwd (no `cd` needed):
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
cmux new-surface --type terminal --working-directory /abs/path/to/repo --pane pane:M --focus false
|
|
75
|
+
cmux send --surface surface:N "claude\n"
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Keep all splits horizontal; stop at 5 claude sessions total.
|
|
79
|
+
|
|
80
|
+
## Leader loop
|
|
81
|
+
|
|
82
|
+
1. **Plan & shard.** Break the goal into independent slices, one per follower (≤5). Pick each slice's
|
|
83
|
+
repo/dir so enact-context warms the right context.
|
|
84
|
+
2. **Spawn & brief.** Split → `cd <dir> && claude` → send a self-contained briefing (role, scope,
|
|
85
|
+
exit criteria, "report back in one line when done/blocked") using the cmux-send envelope.
|
|
86
|
+
3. **Poll.** Round-robin `read-screen` each follower. Watch for: finished, blocked, asking a question,
|
|
87
|
+
or idle at the `❯` prompt.
|
|
88
|
+
4. **Unblock.** Answer questions / re-scope via `send`. Never reach into a follower's repo yourself
|
|
89
|
+
unless you're the session that owns it.
|
|
90
|
+
5. **Verify & gate.** When a follower claims done, verify against real output (tests, build, PR state)
|
|
91
|
+
before you treat the slice as green. Don't accept self-reported green.
|
|
92
|
+
6. **Close.** Summarize across followers; drive the merge / final gate from the leader.
|
|
93
|
+
|
|
94
|
+
## Quick reference (verified surface)
|
|
95
|
+
|
|
96
|
+
| Need | Command |
|
|
97
|
+
|---|---|
|
|
98
|
+
| List sessions | `cmux list-pane-surfaces [--pane pane:N]` |
|
|
99
|
+
| Read a session | `cmux read-screen --surface surface:N --lines 40` |
|
|
100
|
+
| Send + submit | `cmux send --surface surface:N "text\n"` |
|
|
101
|
+
| Submit a parked msg | `cmux send-key --surface surface:N enter` |
|
|
102
|
+
| Flush a queued msg (only if a command is running) | `cmux send-key --surface surface:N ctrl+b` |
|
|
103
|
+
| Interrupt | `cmux send-key --surface surface:N ctrl+c` |
|
|
104
|
+
| New right split | `cmux new-split right --focus false` |
|
|
105
|
+
| Terminal w/ cwd | `cmux new-surface --type terminal --working-directory <path> --pane pane:N` |
|
|
106
|
+
| Focus a pane | `cmux focus-pane --pane pane:N` |
|
|
107
|
+
|
|
108
|
+
Gotchas: agent-session ≠ scriptable (terminal only) · `\n` may not submit during boot/thinking (use
|
|
109
|
+
`send-key enter`) · `read-screen` takes `--surface`, not `--pane` · a `send` to a busy follower queues
|
|
110
|
+
and delivers at turn-end — `ctrl+b` flushes it **only if a command is running** · leader must not `cd`
|
|
111
|
+
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` |
|