Skip to content

Add optional CMUX multi-agent orchestration runbooks - #3

Merged
caseycapshaw merged 2 commits into
mainfrom
add-cmux-support
Jul 9, 2026
Merged

Add optional CMUX multi-agent orchestration runbooks#3
caseycapshaw merged 2 commits into
mainfrom
add-cmux-support

Conversation

@casey-capshaw-rbrk

Copy link
Copy Markdown
Contributor

Summary

  • Adds two optional 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, and pane-level subagent fan-out.
  • Documents the underlying two-interface model (vault = memory/state, orchestration tool = runtime; state round-trips through the vault) as a new paragraph in meta/AGENTS.md § Optional extensions, following the same pattern as the existing Excalidraw extension.
  • Indexes both new runbooks in concepts/jobs.md.

Entirely opt-in — nothing else in the KB depends on this; skip it if you're not running a multi-agent terminal tool.

Test plan

  • Confirm both new files render correctly as Obsidian notes (frontmatter, wikilinks)
  • Confirm [[Delegate an initiative to a CMUX workspace]] and [[Spawn subagent panes in a CMUX workspace]] resolve via meta/bin/lint.sh / link-map tooling
  • Read through for any residual personal/specific content (none intended — this is a generic port)

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.
owner: {{NAME}}
status: active
tags: [job, env]
aliases: [Delegate to a workspace, Spin up a CMUX workspace, Delegate an initiative]

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Schema consistency: this Job adds a new note with aliases:, but meta/link-map.md wasn't regenerated (meta/bin/build-link-map.sh). Per meta/AGENTS.md § Conventions: "Regenerate after adding/renaming any concept, person, or job." Right now none of this job's aliases (or the sibling Spawn subagent panes... job's aliases) resolve via the link map. Same applies to Jobs/Spawn subagent panes in a CMUX workspace.md.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor schema deviation: the ## Model — line sits before the # Job — ... title (h2 before h1), and Jobs/Jobs TEMPLATE.md has no "Model" section at all. Every other job in Jobs/ follows frontmatter → # Job — Title## When to run this → ... Consider either folding this into the frontmatter/blockquote header or moving it under the title so the heading hierarchy and template shape stay consistent. Same pattern in Jobs/Spawn subagent panes in a CMUX workspace.md:13.

tools: cmux, Claude Code, git, Initiatives/
owner: {{NAME}}
status: active
tags: [job, env]

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: tags: [job, env] — the one existing precedent for a second tag mirrors domain: (Optimize the knowledge base.md has domain: kb-meta / tags: [job, kb-meta]). Here domain: kb-meta but the tag is env, which is inconsistent with that pattern. Not blocking, just worth aligning. Same on Jobs/Spawn subagent panes in a CMUX workspace.md:9.

@claude

claude Bot commented Jul 9, 2026

Copy link
Copy Markdown

VERDICT: ISSUES

Reviewed against meta/AGENTS.md § Privacy & content separation and § Conventions.

Privacy: clean. Both new Jobs use owner: {{NAME}} (not a real name), no personal names/emails/addresses/hosts, and the CMUX paths/URLs are generic (public repo link, placeholder $HOME/dev/<repo-or-worktree>, <model-id>).

Schema consistency issues (non-blocking, please fix):

  1. meta/link-map.md was not regenerated (meta/bin/build-link-map.sh) after adding two new Jobs with aliases: — violates the "regenerate after adding/renaming any concept, person, or job" rule in meta/AGENTS.md. Right now none of the new aliases resolve via the link map.
  2. Both new job files open with a ## Model — ... line before the # Job — Title heading (h2 before h1), which isn't part of Jobs/Jobs TEMPLATE.md and breaks from every other job's frontmatter → title → sections shape.
  3. Minor: tags: [job, env] doesn't match the domain: kb-meta these jobs declare — the one existing precedent (Optimize the knowledge base.md) mirrors domain in the second tag ([job, kb-meta]).

Doc coherence: good — concepts/jobs.md indexes both new jobs correctly under KB-meta with owner untouched, meta/AGENTS.md's new "Multi-agent orchestration (CMUX)" paragraph fits the existing "Optional extensions" section pattern (alongside the automation bundle and Excalidraw), and index.md/README.md/setup.md need no changes since they don't enumerate individual jobs.

Left inline comments with specifics. Regenerating the link map is the one I'd actually want fixed before merge; the rest are polish.

- 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 <noreply@anthropic.com>
@claude

claude Bot commented Jul 9, 2026

Copy link
Copy Markdown

VERDICT: PASS

Reviewed the CMUX runbook addition (Jobs/Delegate an initiative to a CMUX workspace.md, Jobs/Spawn subagent panes in a CMUX workspace.md, plus the meta/AGENTS.md § Optional extensions paragraph, concepts/jobs.md index rows, and meta/link-map.md regen).

Privacy: No personal/instance-specific content. owner: {{NAME}} placeholder preserved in both new job frontmatters; example paths/values ($HOME/dev/<repo-or-worktree>, <model-id>, <Colour>, <slug>) are all generic placeholders, not real values. The external link (github.com/disler/learning-cmux-with-agents) is a public tool reference, consistent with how other optional tools (Excalidraw) are cited.

Schema consistency: Both new Jobs are indexed in concepts/jobs.md under 📚 KB-meta with the same table format and *(optional, needs X)* annotation pattern used for the existing Excalidraw job. Frontmatter on both carries type/domain/trigger/frequency/tools/owner/status/tags/aliases. meta/link-map.md was regenerated with all new canonical names + aliases. index.md correctly untouched (Jobs aren't enumerated there — only concepts/jobs.md is, per convention). New [[...]] links all resolve (verified against meta/bin/lint.sh's resolution logic, including the sibling cross-links and [[AGENTS]], which is a hardcoded-valid target).

Doc coherence: The new AGENTS.md paragraph was appended under the existing "## Optional extensions" heading, in the same style as the Excalidraw/automation paragraphs above it. setup.md/README.md don't mention CMUX, but they also don't mention Excalidraw — consistent with the existing precedent that setup-flow docs stay silent on optional/needs-external-tool jobs.

No issues found.

@caseycapshaw
caseycapshaw merged commit b314815 into main Jul 9, 2026
2 checks passed
@caseycapshaw
caseycapshaw deleted the add-cmux-support branch July 9, 2026 15:04
casey-capshaw-rbrk added a commit that referenced this pull request Jul 9, 2026
Two refinements to the CMUX orchestration runbooks landed in #3:

- Launch pane workers lean (`--strict-mcp-config` + empty mcp-config) so a
  large MCP fleet's tool schemas don't crowd out a worker's context — the
  same bloat that can make an in-process subagent/Task tool unusable, which
  is why explicit pane workers are the reliable path. Documented in both
  runbooks + the AGENTS.md § Optional extensions model note.
- Reframe the control-socket wording as a routine, no-setup sanity check
  (the in-pane socket works out of the box under the default cmuxOnly);
  config only matters to drive CMUX from outside a pane.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
caseycapshaw pushed a commit that referenced this pull request Jul 9, 2026
Two refinements to the CMUX orchestration runbooks landed in #3:

- Launch pane workers lean (`--strict-mcp-config` + empty mcp-config) so a
  large MCP fleet's tool schemas don't crowd out a worker's context — the
  same bloat that can make an in-process subagent/Task tool unusable, which
  is why explicit pane workers are the reliable path. Documented in both
  runbooks + the AGENTS.md § Optional extensions model note.
- Reframe the control-socket wording as a routine, no-setup sanity check
  (the in-pane socket works out of the box under the default cmuxOnly);
  config only matters to drive CMUX from outside a pane.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants