From def4763226be8a7c8c86afd569844f27e4c9c6a5 Mon Sep 17 00:00:00 2001 From: Casey Capshaw Date: Thu, 9 Jul 2026 08:52:14 -0600 Subject: [PATCH 1/2] Add optional CMUX multi-agent orchestration runbooks Ports two generic Jobs/ runbooks for driving a CMUX-style terminal multiplexer as an ephemeral runtime layer on top of the vault's durable memory (workspace-level initiative delegation, pane-level subagent fan-out), plus the two-interface model as a new optional-extensions paragraph in meta/AGENTS.md. --- ...egate an initiative to a CMUX workspace.md | 112 ++++++++++++++++++ ...pawn subagent panes in a CMUX workspace.md | 101 ++++++++++++++++ concepts/jobs.md | 2 + meta/AGENTS.md | 20 ++++ 4 files changed, 235 insertions(+) create mode 100644 Jobs/Delegate an initiative to a CMUX workspace.md create mode 100644 Jobs/Spawn subagent panes in a CMUX workspace.md diff --git a/Jobs/Delegate an initiative to a CMUX workspace.md b/Jobs/Delegate an initiative to a CMUX workspace.md new file mode 100644 index 0000000..f0279ca --- /dev/null +++ b/Jobs/Delegate an initiative to a CMUX workspace.md @@ -0,0 +1,112 @@ +--- +type: job +domain: kb-meta +trigger: an initiative/task is ready to run in its own repo context, delegated from the main workspace +frequency: per-initiative +tools: cmux, Claude Code, git, Initiatives/ +owner: {{NAME}} +status: active +tags: [job, env] +aliases: [Delegate to a workspace, Spin up a CMUX workspace, Delegate an initiative] +--- + +## Model — orchestrator: a capable model (Claude Code lead). Delegated workspace agent: a capable or cheaper model by task weight. + +# Job — Delegate an initiative to a CMUX workspace + +> **When:** the main workspace needs to hand a whole task/initiative to its own +> CMUX workspace (own repo/worktree, own agent) · **Frequency:** per-initiative · +> **Tools:** `cmux` CLI, Claude Code, git, the initiative note +> **Outcome:** a dedicated, colour-coded CMUX workspace running its own Claude +> Code on the right `--cwd`, kicked off against an `Initiatives/.md` note +> that is the shared source of truth — with the dispatch recorded back in that note. + +## When to run this +The unit of work is a **whole workstream** that wants its own repo context and +lifecycle — not a fan-out of sub-tasks within one session (that's +[[Spawn subagent panes in a CMUX workspace]]). You're operating from the **main +workspace** (Claude Code orchestrator, cwd = your vault root). This is an +**optional extension** — see `meta/AGENTS.md` § Optional extensions for the +two-interface model behind it (vault = memory/durable, CMUX = runtime/ephemeral; +state round-trips through the vault). **Precondition:** the initiative has a note +in `Initiatives/` (if not, run [[Run an initiative]] first) — that note is the +delegated workspace's `backlog.md`. + +## Steps +1. **Preflight the socket.** `cmux identify --json` should succeed. If not, launch + CMUX and poll: + ```bash + cmux identify --json >/dev/null 2>&1 || { open -a cmux; \ + for i in $(seq 1 30); do cmux identify --json >/dev/null 2>&1 && break; sleep 0.5; done; } + ``` + (`cmux` = `/Applications/cmux.app/Contents/Resources/bin/cmux` — symlink it onto PATH once.) +2. **Pick the window.** Reuse the current one: `WIN=$(cmux list-windows --json | jq -r '.[0].id')`. +3. **Create the workspace on the initiative's cwd** — a repo checkout or a + worktree. Capture the refs: + ```bash + read WS LEAD < <(cmux workspace create --window "$WIN" --name "" \ + --cwd "$HOME/dev/" --focus true --json \ + | jq -r '[.workspace_ref,.surface_ref]|@tsv') + ``` + Add `--env-file ./.env` when the workspace needs credentials injected. +4. **Make it legible** — colour + status so it's scannable in the sidebar: + ```bash + cmux rename-tab --workspace "$WS" --surface "$LEAD" "🎯 " + cmux workspace-action --action set-color --workspace "$WS" --color + cmux set-status initiative "" --workspace "$WS" + ``` +5. **Launch the delegated Claude Code** into the lead surface (pick the model by + task weight — a cheaper model for well-scoped execution, a more capable one + for heavy reasoning): + ```bash + cmux send --surface "$LEAD" "claude --model " + cmux send-key --surface "$LEAD" enter + sleep 4 + ``` +6. **Kick it off with a one-line brief** that points at the vault note as its + source of truth and demands a sentinel on completion. **One line, no newlines:** + ```bash + cmux send --surface "$LEAD" "Read /Initiatives/.md; execute its Now-and-next; write decisions/actions back to that note; end with: DONE: | " + cmux send-key --surface "$LEAD" enter + ``` +7. **Record the dispatch in the vault** *(this is the round-trip — do not skip)* — + in `Initiatives/.md` add a dated Milestone ("delegated to CMUX workspace + `` on ``, ") and any `#action`s you're now waiting on. +8. **Coordinate to completion** (event-driven, not busy-poll): + ```bash + cmux events --category notification --reconnect | grep -m1 "$WS" >/dev/null + cmux read-screen --surface "$LEAD" --scrollback --lines 60 | tail -30 + ``` + **Confirm the `DONE:` sentinel actually printed** before trusting it — a wake + can mean "needs input", not "finished". If it's asking for input, `send` the + answer + `send-key enter`. +9. **Close out.** When the initiative note reflects the outcome (results, decisions, + next actions written back), tear the workspace down: `cmux workspace close + --workspace "$WS"` (or keep it if work continues). The vault, not CMUX, is the record. + +## Gotchas / rules +- **State lives in the vault, not the workspace.** A CMUX workspace is disposable; + if the plan/result isn't written into `Initiatives/.md`, it's lost on + teardown. Step 7 + step 9 are the whole point. +- **`send` types; `send-key enter` submits.** A `send` with no follow-up `enter` + leaves the prompt unsent. **Never put a `\n` inside a `send`** — each newline + fires a half-finished turn; keep briefs to one line and split if long. +- **Thread the refs.** Always capture `workspace_ref`/`surface_ref` from `--json` + and reuse them — never guess a surface address. +- **Notify ≠ done.** Always `read-screen` and confirm the sentinel; agents notify + when they need input too. +- **`socketControlMode: cmuxOnly` is fine** for an orchestrator running inside a + CMUX pane (the default). Only raise to `allowAll` if you drive from outside CMUX. +- **One workspace = one repo context.** If the "delegation" is really N concurrent + sub-tasks sharing one context, use panes instead → [[Spawn subagent panes in a CMUX workspace]]. + +## Done when +- [ ] A dedicated CMUX workspace is running its own Claude Code on the right `--cwd`, kicked off against the initiative note. +- [ ] The dispatch (and, at close, the outcome) is written back into `Initiatives/.md`. +- [ ] The `DONE:` sentinel was confirmed via `read-screen` (not assumed from a notification). + +## Related +- `meta/AGENTS.md` § Optional extensions — the model + why (the two-interface split, the round-trip rule). +- [[Spawn subagent panes in a CMUX workspace]] — sibling runbook for pane-level fan-out. +- [[Run an initiative]] — creates/maintains the `Initiatives/` note this delegates against. +- [[AGENTS]] diff --git a/Jobs/Spawn subagent panes in a CMUX workspace.md b/Jobs/Spawn subagent panes in a CMUX workspace.md new file mode 100644 index 0000000..1b2fe8f --- /dev/null +++ b/Jobs/Spawn subagent panes in a CMUX workspace.md @@ -0,0 +1,101 @@ +--- +type: job +domain: kb-meta +trigger: one task decomposes into concurrent sub-tasks you want to run and watch as panes +frequency: ad-hoc +tools: cmux, Claude Code +owner: {{NAME}} +status: active +tags: [job, env] +aliases: [Spawn subagent panes, Fan out subagents, Subagent panes, Spawn workers in panes] +--- + +## Model — lead: a capable model (coordinates, doesn't do the heavy edits). Worker panes: a cheaper/faster model where appropriate. + +# Job — Spawn subagent panes in a CMUX workspace + +> **When:** a single task fans out into concurrent sub-tasks you want visible and +> drivable as panes in the current workspace · **Frequency:** ad-hoc · +> **Tools:** `cmux` CLI, Claude Code +> **Outcome:** N worker agents running in split panes, each driven by the session +> lead through the four-verb loop, each reporting a `DONE:` sentinel — torn down +> when finished. + +## When to run this +The work is **one task with concurrent legs that share a context** (e.g. +research three sources at once; build + test in parallel), not a whole workstream +needing its own repo (that's [[Delegate an initiative to a CMUX workspace]]). +You're the **lead** in an existing workspace. This is an **optional extension** — +see `meta/AGENTS.md` § Optional extensions for the model + why (the two-interface +split, the four-verb loop, model policy). **The lead coordinates — it does not do +the heavy editing itself once workers exist.** + +## Steps +1. **Know your own surface.** From the lead pane, `cmux identify --json` (socket + check) and `cmux list-pane-surfaces` to see the workspace + your surface ref. + Set `WS=` and `LEAD=`. +2. **Split off worker panes** — anchor each split on an existing surface; capture + each new ref. E.g. three workers: + ```bash + W1=$(cmux new-split right --workspace "$WS" --surface "$LEAD" --json | jq -r .surface_ref) + W2=$(cmux new-split down --workspace "$WS" --surface "$W1" --json | jq -r .surface_ref) + W3=$(cmux new-split down --workspace "$WS" --surface "$LEAD" --json | jq -r .surface_ref) + ``` +3. **Label them** so the grid is scannable: `cmux rename-tab --workspace "$WS" + --surface "$W1" "🔬 research-A"` (repeat per worker); optional `cmux + trigger-flash --surface "$W1"` to point at one. +4. **Launch an agent in each pane** (a cheaper/faster model for well-scoped legs). + `send` the CLI line, then `send-key enter`, and give it a moment to boot: + ```bash + for S in "$W1" "$W2" "$W3"; do + cmux send --surface "$S" "claude --model " + cmux send-key --surface "$S" enter + done + sleep 4 + ``` +5. **Dispatch one single-line task per worker**, each ending in a sentinel. **One + line, no embedded newlines:** + ```bash + cmux send --surface "$W1" ". End with exactly: DONE: research-A | " + cmux send-key --surface "$W1" enter + # repeat for W2, W3 + ``` +6. **Wait on the doorbell, then confirm** — block on the notification stream, then + read the pane and check the sentinel actually printed: + ```bash + cmux events --category notification --reconnect | grep -m1 "$W1" >/dev/null + cmux read-screen --surface "$W1" --scrollback --lines 80 | tail -30 + ``` + One event stream serves all workers for parallel dispatch. A wake can mean + "needs input" — if so, `send` the answer + `send-key enter`, don't mark it done. +7. **Integrate + write back.** The lead collects each worker's result and folds it + into the deliverable / the relevant vault note (concept, initiative, daily + note). Route any failure back to the responsible worker with a follow-up `send`. +8. **Tear down** finished panes: `cmux close-surface --surface "$W1"` (repeat). + Close a runaway the same way. + +## Gotchas / rules +- **`send` types, `send-key enter` submits; never embed `\n`** — each newline + fires a separate half-finished turn. One line per `send`. +- **Thread refs from `--json`** — capture every `surface_ref` at creation; never + guess an address. +- **Notify ≠ done** — always `read-screen` and confirm the `DONE:` sentinel; agents + notify when they need input too. Wait on events; **don't busy-poll**. +- **Lead doesn't do the heavy lifting** once workers exist — it decomposes, + dispatches, integrates, reports. Keep its own edits to integration. +- **Panes share the workspace cwd/context** — if a leg needs a different repo, it's + a workspace-level delegation instead → [[Delegate an initiative to a CMUX workspace]]. +- **Claude Code's own Task/Agent subagents are in-process**, not CMUX panes. This + runbook is the explicit-pane path (visible, drivable). Some CMUX versions can + surface native subagents as panes automatically — untested; prefer explicit + `new-split` for now. + +## Done when +- [ ] N worker panes launched, labelled, and each dispatched a one-line task with a sentinel. +- [ ] Every worker's `DONE:` sentinel confirmed via `read-screen`; results integrated by the lead and written to the right vault note. +- [ ] Finished panes torn down with `close-surface`. + +## Related +- `meta/AGENTS.md` § Optional extensions — the model + why (the four-verb loop, coordination patterns, model policy). +- [[Delegate an initiative to a CMUX workspace]] — sibling runbook for workspace-level (whole-task) delegation. +- [[AGENTS]] diff --git a/concepts/jobs.md b/concepts/jobs.md index 3ea2e4e..dbc01ee 100644 --- a/concepts/jobs.md +++ b/concepts/jobs.md @@ -30,6 +30,8 @@ Jobs for maintaining the knowledge base itself — always useful, ship with the | [[Optimize the knowledge base]] | monthly / when the KB feels bloated | efficiency pass: injection budget · index-as-map · frontmatter staleness · link-map · lint | | [[Sync an improvement to CNTXT1]] | a generic schema/tooling/template change is worth sharing | the ONLY outward path — manual copy + re-template + grep gate; personal content never leaves the vault (`AGENTS.md` § Privacy) | | [[Create an Excalidraw diagram]] | need a diagram / visual in the vault *(optional)* | zero-dep `meta/bin/excalidraw.py` (spec→file) or Mermaid by hand; text ids ≤8 chars or the mirror breaks | +| [[Delegate an initiative to a CMUX workspace]] | an initiative is ready to run in its own repo context *(optional, needs CMUX)* | workspace-level delegation; state round-trips through `Initiatives/.md`, not the runtime tool | +| [[Spawn subagent panes in a CMUX workspace]] | one task fans out into concurrent sub-tasks *(optional, needs CMUX)* | pane-level fan-out; four-verb loop (send/send-key/read-screen/close-surface) + `DONE:` sentinel | ## 🛠️ Dev _(add job runbooks for your recurring dev tasks)_ diff --git a/meta/AGENTS.md b/meta/AGENTS.md index e55589e..a3dd686 100644 --- a/meta/AGENTS.md +++ b/meta/AGENTS.md @@ -111,3 +111,23 @@ zero-dependency generator that emits native Obsidian-Excalidraw `.excalidraw.md` files (shapes + bound labels + auto-routing arrows) from a compact Python node/edge spec — no npm, no browser, no network. Files land in the optional `Excalidraw/` structural folder. See `Jobs/Create an Excalidraw diagram.md`. + +**Multi-agent orchestration (CMUX)** is a further optional *runtime* layer, for +anyone running a terminal multiplexer/agent-orchestration tool (e.g. +[CMUX](https://github.com/disler/learning-cmux-with-agents)) alongside this KB. +The model: two interfaces with a clean division of labour — the **vault stays +memory/state** (durable — initiatives, actions, concepts) and the **orchestration +tool is runtime** (ephemeral — windows/workspaces/panes, spun up and torn down +per task). **State round-trips through the vault, not through the runtime tool**: +whatever gets dispatched, and whatever comes back (decisions, milestones, +follow-up `#action`s), gets written into the relevant `Initiatives/.md` +note — if it isn't in the vault, it didn't happen. Two granularities of +delegation, each its own runbook: workspace-level (a whole initiative gets its +own repo context and its own agent — `Jobs/Delegate an initiative to a CMUX +workspace.md`) and pane-level (one task fans out into concurrent sub-tasks +sharing a context — `Jobs/Spawn subagent panes in a CMUX workspace.md`). Both +runbooks use the same four-verb control loop (type → submit → read → close), +event-driven coordination (a `DONE: ` sentinel — "notify" from the tool +isn't the same as "done"), and a model policy of a more capable model as +lead/orchestrator with cheaper/faster models as workers. Entirely optional — +skip it if you're not running a multi-agent terminal tool. From 8470262b1e13cceae62fb51788cd1ab9970812dc Mon Sep 17 00:00:00 2001 From: Casey Capshaw Date: Thu, 9 Jul 2026 09:00:24 -0600 Subject: [PATCH 2/2] Address review: regen link map, fix job heading order and tags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Regenerate meta/link-map.md so the two new CMUX jobs and their aliases resolve - Fold the pre-title "## Model" line into each job's summary blockquote, restoring the template's frontmatter → title → sections shape - Mirror domain in tags: [job, env] → [job, kb-meta] Co-Authored-By: Claude Fable 5 --- Jobs/Delegate an initiative to a CMUX workspace.md | 6 +++--- Jobs/Spawn subagent panes in a CMUX workspace.md | 6 +++--- meta/link-map.md | 9 +++++++++ 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/Jobs/Delegate an initiative to a CMUX workspace.md b/Jobs/Delegate an initiative to a CMUX workspace.md index f0279ca..bc83668 100644 --- a/Jobs/Delegate an initiative to a CMUX workspace.md +++ b/Jobs/Delegate an initiative to a CMUX workspace.md @@ -6,12 +6,10 @@ frequency: per-initiative tools: cmux, Claude Code, git, Initiatives/ owner: {{NAME}} status: active -tags: [job, env] +tags: [job, kb-meta] aliases: [Delegate to a workspace, Spin up a CMUX workspace, Delegate an initiative] --- -## Model — orchestrator: a capable model (Claude Code lead). Delegated workspace agent: a capable or cheaper model by task weight. - # Job — Delegate an initiative to a CMUX workspace > **When:** the main workspace needs to hand a whole task/initiative to its own @@ -20,6 +18,8 @@ aliases: [Delegate to a workspace, Spin up a CMUX workspace, Delegate an initiat > **Outcome:** a dedicated, colour-coded CMUX workspace running its own Claude > Code on the right `--cwd`, kicked off against an `Initiatives/.md` note > that is the shared source of truth — with the dispatch recorded back in that note. +> **Model:** orchestrator — a capable model (Claude Code lead); delegated +> workspace agent — a capable or cheaper model by task weight. ## When to run this The unit of work is a **whole workstream** that wants its own repo context and diff --git a/Jobs/Spawn subagent panes in a CMUX workspace.md b/Jobs/Spawn subagent panes in a CMUX workspace.md index 1b2fe8f..ef90fa6 100644 --- a/Jobs/Spawn subagent panes in a CMUX workspace.md +++ b/Jobs/Spawn subagent panes in a CMUX workspace.md @@ -6,12 +6,10 @@ frequency: ad-hoc tools: cmux, Claude Code owner: {{NAME}} status: active -tags: [job, env] +tags: [job, kb-meta] aliases: [Spawn subagent panes, Fan out subagents, Subagent panes, Spawn workers in panes] --- -## Model — lead: a capable model (coordinates, doesn't do the heavy edits). Worker panes: a cheaper/faster model where appropriate. - # Job — Spawn subagent panes in a CMUX workspace > **When:** a single task fans out into concurrent sub-tasks you want visible and @@ -20,6 +18,8 @@ aliases: [Spawn subagent panes, Fan out subagents, Subagent panes, Spawn workers > **Outcome:** N worker agents running in split panes, each driven by the session > lead through the four-verb loop, each reporting a `DONE:` sentinel — torn down > when finished. +> **Model:** lead — a capable model (coordinates, doesn't do the heavy edits); +> worker panes — a cheaper/faster model where appropriate. ## When to run this The work is **one task with concurrent legs that share a context** (e.g. diff --git a/meta/link-map.md b/meta/link-map.md index 1c228ac..49c4038 100644 --- a/meta/link-map.md +++ b/meta/link-map.md @@ -13,7 +13,11 @@ Resolves every `[[target]]` the KB uses (canonical names + registered `aliases:` | `[[Contribute to CNTXT1]]` | `Jobs/Sync an improvement to CNTXT1.md` | | `[[Create an Excalidraw diagram]]` | `Jobs/Create an Excalidraw diagram.md` | | `[[Create Excalidraw]]` | `Jobs/Create an Excalidraw diagram.md` | +| `[[Delegate an initiative to a CMUX workspace]]` | `Jobs/Delegate an initiative to a CMUX workspace.md` | +| `[[Delegate an initiative]]` | `Jobs/Delegate an initiative to a CMUX workspace.md` | +| `[[Delegate to a workspace]]` | `Jobs/Delegate an initiative to a CMUX workspace.md` | | `[[Excalidraw diagram]]` | `Jobs/Create an Excalidraw diagram.md` | +| `[[Fan out subagents]]` | `Jobs/Spawn subagent panes in a CMUX workspace.md` | | `[[jobs]]` | `concepts/jobs.md` | | `[[karpathy-method]]` | `concepts/karpathy-method.md` | | `[[KB efficiency pass]]` | `Jobs/Optimize the knowledge base.md` | @@ -23,7 +27,12 @@ Resolves every `[[target]]` the KB uses (canonical names + registered `aliases:` | `[[Optimize the knowledge base]]` | `Jobs/Optimize the knowledge base.md` | | `[[Run an initiative]]` | `Jobs/Run an initiative.md` | | `[[Run the KB health check]]` | `Jobs/Run the KB health check.md` | +| `[[Spawn subagent panes in a CMUX workspace]]` | `Jobs/Spawn subagent panes in a CMUX workspace.md` | +| `[[Spawn subagent panes]]` | `Jobs/Spawn subagent panes in a CMUX workspace.md` | +| `[[Spawn workers in panes]]` | `Jobs/Spawn subagent panes in a CMUX workspace.md` | +| `[[Spin up a CMUX workspace]]` | `Jobs/Delegate an initiative to a CMUX workspace.md` | | `[[Start an initiative]]` | `Jobs/Run an initiative.md` | +| `[[Subagent panes]]` | `Jobs/Spawn subagent panes in a CMUX workspace.md` | | `[[Sync a KB improvement to the shared repo]]` | `Jobs/Sync an improvement to CNTXT1.md` | | `[[Sync an improvement to CNTXT1]]` | `Jobs/Sync an improvement to CNTXT1.md` | | `[[Tune the knowledge base]]` | `Jobs/Optimize the knowledge base.md` |