[teamleaderleo]

Leo-ask: ask-a933b133a7
Leo-Ask-Trace: ask-a933b133a7

Leo, 2026-11-05, looking at the Claude Code desktop app's task list, proposed-session cards, session links and wrap-up box: "presumably specifically in the claude code desktop there are a few skills/system prompts that let you guys know about them... cmux-next should add a few and we can think about extending them as well and letting other users define stuff too!"

Design and audit of what agents were told before: plans/cmux-next/agent-guidance-DESIGN.md.

What every agent cmux runs now gets

Five pieces of guidance, each tied to a tool cmux already has and saying when it applies:

Piece	Applies when	Tool
Plan list	a task with more than one step	Claude Code TodoWrite, Codex update_plan (drawn as the chat's checklist)
Side sessions	the person asked for parallel work; otherwise offer it	start_session, offer_session, suggest_tasks, app_agent_open
Session links	mentioning another session	a session name or agent link in inline code (drawn as a chip)
Closing recap	a turn that changed files or ran commands	the reply's last lines
Editing cmux live	asked to change how cmux looks or behaves	cmux-live, cmux-customization skills

Each harness gets it through its own mechanism:

• Claude Code: a new skill cmux:cmux-chat in the session plugin (only its description is in the prompt), plus a short first-turn pointer so the plan and recap rules hold before the skill is read.
• Codex and other harnesses: the compact guidance in the first-turn context, the same user-role channel Codex uses for AGENTS.md. Nothing is written to the person's CODEX_HOME or repo.

The guidance is its own context part (cmux-guidance), so a person's Context viewer override of the default rule keeps it. The Context viewer lists it with its tokens.

The person's layer

• Skills in ~/.config/cmux/skills/<name>/SKILL.md (standard SKILL.md frontmatter). Claude Code gets them as a second session plugin, cmux-user:<name> (regular files only, no symlinks, size and count limits, written once per content hash). Other harnesses get an index (name, description, path) and read the file when it applies.
• Switches, all on by default, user-only (agents may not set them): agents.guidance.claude, agents.guidance.codex, agents.guidance.otherAgents, agents.guidance.userSkills, in Settings > Agents > Guidance and Skills, the palette, cmux settings, and MCP settings_get. They apply to new chats.

Verification

• Fleet Rust at 0ccb29e (run 42006331368): cargo fmt --check, cargo test -p acpmux --lib (agent_guidance, context_inventory, agent_tools, prompt_line_tests: 41 passed), --test tool_inventory, --test hub_integration prompt_context, cargo clippy -p acpmux --all-targets -D warnings: all pass.
• Fleet Swift: AgentGuidanceSettingsTests pass. SettingsSchemaExportTests.exportIsFresh fails only because settings-schema.json is generated; base autofix regenerates it (never hand-edited).
• Real Codex session (codex-cli 0.164.0, an acpmux built at this branch, its own daemon home, one user skill whose body holds a canary word): asked to quote any cmux guidance, state the end-of-turn rule and follow a matching skill, it answered "cmux chat guidance (cmux defaults; the person's own instructions win).", A two-or-three-sentence recap covering what is true, verified, unfinished, and any decision needed. and PELICAN-42: Tag the commit, then write the notes. The canary is only in the user skill, so the skill index reached Codex and it read the skill.
• Real Claude Code session: started with cmux:cmux-chat and cmux-user:release-checklist attached (session tool rows), but no turn completed: the model gateway returned repeated 529 Overloaded on one host, and the Claude login on the other is at its weekly limit. Not yet shown in use.

Observed / Not run

Observed: the runs above. Not run: a tagged app build (the palette row, cmux settings get|set agents.guidance.codex, MCP settings_get), and a completed Claude Code turn.

Changelog

• Added: agents in cmux chats keep a checklist plan, link other sessions and end with a recap; your own skills in ~/.config/cmux/skills reach every chat; Settings > Agents > Guidance and Skills.

acpmux owner (PL-acpmux) notice: plans/cmux-next/acpmux-audit.md. Sibling work this builds beside: the plan rendering ("Agent plans in cmux chats") and the Live Web Reload PR that adds the cmux-live skill.

Agent session: agent session

🤖 Generated with Claude Code

---

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}

---

Summary by cubic

Agents in cmux chats now know how cmux shows their work, and the person's own skills reach every chat.

Built-in guidance

• A new cmux:cmux-chat skill tells Claude Code to keep a plan checklist, start sub-sessions only when asked (offer them otherwise), link sessions in inline code, and end changed turns with a recap. A short first-turn pointer says when to read it, and side-session tools are named only when cmux lists them, so the pointer stays around 95 tokens.
• Codex and other harnesses get the same guidance as first-turn context via the channel Codex uses for AGENTS.md; nothing is written to the person's CODEX_HOME or repo.
• The guidance is its own first-turn context part reviewed in the Context viewer, kept beside the folder-instructions part from the base branch in new sessions and fresh forks.

The person's layer

• Skills in ~/.config/cmux/skills/<name>/SKILL.md reach every chat: a cmux-user plugin for Claude Code (regular files only, with SKILL.md files copied first under a 32 MiB overall budget and per-file limits so a stray huge folder is not copied on each session start; a symlinked SKILL.md is refused), and an index for other agents whose descriptions are cut at 300 characters.
• New user-only switches agents.guidance.{claude,codex,otherAgents,userSkills} (on by default) in Settings > Agents > Guidance and Skills apply to chats created after the change; turning off the Claude switch also leaves cmux-chat out of the plugin.

^{Written for commit c857477. Summary will update on new commits.}

[cursor]

Bugbot needs on-demand usage enabled

Bugbot uses usage-based billing for this team and requires on-demand usage to be enabled.

A team admin can enable on-demand usage in the Cursor dashboard.

[github-actions]

cmux status _{(one comment, edited in place; each line is updated by the job that owns it)}

Review c857477: HQ feed card · gallery before/after runs · checks

App of this head (app.zip, kept 1 day)

gh workflow run reload-build.yml -R manaflow-ai/cmux --ref feat-cmux-next -f tag=pr36411 -f ref=lane/agent-guidance-skills -f platform=macos -f backend_mode=local

web and size checks: green

[teamleaderleo]

Owned by an agent session · session

[blacksmith-sh]

Found 15 test failures on Blacksmith runners:

Failures

Test	View Logs
/tmp/tmp_e6qu0qf/summary-fail.json (live):/summary-fail.json (live):	View Logs
/tmp/tmps5qakx84/summary-missing.json (live):/summary-missing.json (live):	View Logs
[new_workspaces] debug.new_workspace timed 0 of 50 new workspace rows/ [new_workspaces] debug.new_workspace timed 0 of 50 new workspace rows	View Logs
[new_workspaces] the window draws no frames/[new_workspaces] the window draws no frames	View Logs
[tabs] debug.tab_switch timed 0 of 40 switches/ [tabs] debug.tab_switch timed 0 of 40 switches	View Logs
[tabs] the window draws no frames/[tabs] the window draws no frames	View Logs
test_big_red (main.FleetRuleLints.test_big_red)/ test_big_red (main.FleetRuleLints.test_big_red)	View Logs
test_checked_in_tree_matches_its_ratchet (main.ShortTimeoutGuardTests.test_checked_ in_tree_matches_its_ratchet)/ test_checked_in_tree_matches_its_ratchet (main.ShortTimeoutGuardTests.test_checked_ in_tree_matches_its_ratchet)	View Logs
test_every_compile_job_names_its_warm_sources (main.ThisTree.test_every_compile_job _names_its_warm_sources)/ test_every_compile_job_names_its_warm_sources (main.ThisTree.test_every_compile_job _names_its_warm_sources)	View Logs
test_every_depth_fetch_checks_for_a_shallow_checkout (main.NoShallowDevFetchTests.t est_every_depth_fetch_checks_for_a_shallow_checkout)/ test_every_depth_fetch_checks_for_a_shallow_checkout (main.NoShallowDevFetchTests.t est_every_depth_fetch_checks_for_a_shallow_checkout)	View Logs

...and 5 more test failures. View all on Blacksmith: run 42037465781, run 42037465497

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[teamleaderleo]

For the owner: this PR is Leo's ask ask-a933b133a7 (asks cluster c-a933b133a7, 3 h SLA from 09:10Z). Please add these two lines to the body so the asks reconciler links it, and land on the independent review once it posts:

Leo-ask: ask-a933b133a7
Leo-Ask-Trace: ask-a933b133a7

A Codex router-review of this head has been started.

[teamleaderleo]

Review (subagent claude-opus-5-5 medium): BLOCK at 1100929
Visual verdict: no images; native settings rows only [follow-up for images]
Checked agent_guidance.rs (skill scan, symlink skipping, plugin write per content hash with tmp+rename), the first-turn path (append_snapshot still runs once under cmux_context_delivered; guidance is its own cmux-guidance part, so a person's Context override is kept), fork/lifecycle snapshots, the user-only and default-on Swift settings, and the cmux-chat SKILL.md against the real tool and server names. I ran the send-path cap matcher from tests/test_send_path_caps.py on the new file. The optchat-chief and rust-workspaces reds don't come from this diff (it touches nothing they compile), and SettingsSchemaExportTests is the known generated-file red.

Findings:
F1 [blocking] ci: tests/test_send_path_caps.py flags 2 new caps, MAX_FILES_PER_SKILL and MAX_FILE_BYTES (decl hits at cmux-tui/crates/acpmux/src/agent_guidance.rs:36-37), and this file has no entry in tests/send-path-cap-allowlist.json. "Validate send-path caps" is in the cmux-next CI guard group. That group is red on this head and green on the current feat-cmux-next tip, so merging this would turn the base red. Fix: add an allowlist entry {"count": 2, "reason": "safe: bounds copying the person's skill folder into the session plugin; never refuses a message or file"}, or drop the caps. outcome:pending
F2 [follow-up] correctness: the new guidance tells agents to write the recap as text ("the last thing you write"). The acpmux MCP wrap_up tool's STEER (acpmux_mcp_wrap_up.rs) says to call wrap_up as the last step and not to repeat the recap. Chats that have both get conflicting instructions and may recap twice or skip the box. SKILL.md and AGENT_GUIDANCE should say to use wrap_up when it is listed (skills/cmux-chat/SKILL.md:62, agent_guidance.rs:49). outcome:pending
F3 [follow-up] correctness: user_skills keeps only real directories (DirEntry::file_type does not follow symlinks). A skill folder symlinked into ~/.config/cmux/skills, which is common, is silently ignored. A SKILL.md that is itself a symlink is indexed, but collect_files leaves it out of the plugin, so the plugin's skill folder has no SKILL.md (agent_guidance.rs:142, 309). outcome:pending
F4 [follow-up] efficiency: user_plugin runs on every tools resolve, for non-Claude harnesses too. Each time it reads and hashes every skill file (up to 64 × 200 × 1 MiB) into memory with sync I/O. Old user-<hash> folders are never pruned (agent_tools.rs:1030, agent_guidance.rs:246). outcome:pending
F5 [follow-up] correctness: frontmatter reads a YAML block scalar (description: > or |) as the literal ">" or "|", and a multi-line description is cut to its first line (agent_guidance.rs:181). outcome:pending
F6 [follow-up] docs: AGENT_GUIDANCE and SKILL.md point to a cmux-live skill that no SKILL.md in the repo defines. SKILL.md also names app_agent_open "(server cmux)", but in a cmux chat it is reached through cmux_exec (cmux.app_agent_open) (agent_guidance.rs:50, SKILL.md:49). outcome:pending
F7 [follow-up] ci: the clippy panic ratchet is over baseline in crates this PR doesn't touch, so most of that red is not this PR's. Still, the new depth + 1 and &hash[..16] in agent_guidance.rs add a hit or two to acpmux; check them when the baseline is refreshed. outcome:pending

Follow-ups: F2-F7 (one tracker Follow-ups: #36411 ...)

[teamleaderleo]

Finding outcome: comment-6656423850/F1 fixed 48dec5a

F2-F7 go to a follow-up tracker.

[teamleaderleo]

Review (subagent claude-opus-5-5 medium): SHIP at 48dec5a
Visual verdict: no images; native settings rows only [follow-up]
The only change since 1100929 is the agent_guidance.rs entry in tests/send-path-cap-allowlist.json (count 2, matching MAX_FILES_PER_SKILL and MAX_FILE_BYTES); the JSON parses and the safe: reason is accurate, since the caps only bound the copy of ~/.config/cmux/skills into the session plugin and refuse no message, prompt or attachment. That clears F1. I re-read the full diff (the Rust guidance and user-plugin module, the prompt_sources and context_inventory wiring, the fork path, the fake-agent tag lists and the settings schema) and found nothing new that blocks: the other AgentTools literals use ..Default::default(), the generated settings file follows existing precedent, and a failed plugin copy is logged and the session starts anyway. CI at this head: 24 pass, 37 pending, no failures.
Follow-ups: tracked in the #36411 follow-up issue (F2-F7).

[teamleaderleo]

Review (codex, router-review): SHIP at 48dec5a

Reviewer: codex gpt-6-astra high, fast tier.

Leo-Ask-Trace: ask-a933b133a7

Follow-ups: 1. They land as checklist items in this PR's one follow-up tracking issue in this repo (Follow-ups: #N ..., label follow-up; add to an open one before filing, never one issue per finding), linking this receipt; the lane that opened the PR fixes them forward.

SHIP at 48dec5a

Visual verdict: no images; Leo tries the build

• [P2] [follow-up] [category:security] [finding:F1] [outcome:pending] cmux-tui/crates/acpmux/src/agent_guidance.rs:148 checks SKILL.md with metadata, which follows symlinks. A symlinked SKILL.md with valid frontmatter is therefore indexed and exposed to non-Claude agents, despite the documented “regular files only, no symlinks” policy; Claude’s plugin copy then inconsistently omits that file because collect_files skips symlinks. Use symlink_metadata/file_type before accepting the file.

Follow-ups:

• F1: reject symlinked SKILL.md files consistently.

[cmux-bot]

cmux-bot approves 48dec5a: an independent review passed this exact head (router-review receipt by teamleaderleo). A push needs a new review; a later BLOCK at this head dismisses this approval.

[teamleaderleo]

Review (codex gpt-6.1-sol xhigh, router-review): BLOCK at 6c9369d

Leo-Ask-Trace: ask-a933b133a7

BLOCK at 6c9369d

Visual verdict: no images; Leo tries the build

• [P1] [blocking] [category:reliability] [finding:F1] [outcome:pending] tree/cmux-tui/crates/acpmux/src/agent_guidance.rs:264 — User-skill copying has no aggregate size cap. The per-skill limits permit 64 × 200 × 1 MiB (about 12.8 GB), and files retains all bytes before all duplicates them for hashing at line 281. A valid skills directory can therefore OOM acpmux or fill its state volume on the first Claude spawn.

• [P1] [follow-up] [category:correctness] [finding:F2] [outcome:pending] tree/cmux-tui/crates/acpmux/src/context_inventory.rs:363, tree/cmux-tui/crates/acpmux/src/agent_tools.rs:489 — Guidance is snapshotted when the chat is created, but Claude plugin settings and user skills are reread on every respawn. Changing a switch before an existing chat resumes can leave a cmux-chat pointer with no plugin, or attach skills to a chat created while they were disabled. Pin these inputs to the session snapshot.

• [P2] [follow-up] [category:correctness] [finding:F3] [outcome:pending] tree/cmux-tui/crates/acpmux/src/agent_tools.rs:838, tree/cmux-tui/crates/acpmux/src/agent_tools/prompt_sources.rs:146 — With agents.guidance.claude=false, materialization removes cmux-chat, but tool rows and context-source metadata still enumerate every static SKILL_FILES entry. The chat therefore advertises a skill that is absent from its plugin.

Follow-ups:

• F2 — Pin guidance and user-skill inputs per chat.
• F3 — Filter inventory rows and metadata using the same skill set materialized for the session.

[teamleaderleo]

Review (codex, router-review): SHIP at 4090d55

Reviewer: codex gpt-6-astra high, fast tier.

Leo-Ask-Trace: ask-a933b133a7

Follow-ups: 2. They land as checklist items in this PR's one follow-up tracking issue in this repo (Follow-ups: #N ..., label follow-up; add to an open one before filing, never one issue per finding), linking this receipt; the lane that opened the PR fixes them forward.

SHIP at 4090d55

Visual verdict: no images; Leo tries the build

• [P1] [follow-up] [category:correctness] [finding:F1] [outcome:pending] Guidance is snapshotted when the chat is created, but Claude’s plugin and user-skill switches are reread at spawn time (lifecycle.rs:272, agent_tools.rs:669). A delayed chat can therefore receive a first-turn pointer that disagrees with the actual plugin contents, violating the documented “applies to chats created after the change” behavior.

• [P2] [follow-up] [category:correctness] [finding:F2] [outcome:pending] When agents.guidance.claude is false, materialize removes cmux-chat, but tool_rows and context_parts still enumerate every static SKILL_FILES entry (agent_tools.rs:838, prompt_sources.rs:146). The tools/context inventory falsely advertises a disabled skill.

Follow-ups:

• [finding:F1] Snapshot guidance/plugin switch state at chat creation.
• [finding:F2] Track/filter the actual compiled skill set in inventory generation.

[cmux-bot]

cmux-bot approves 4090d55: an independent review passed this exact head (router-review receipt by teamleaderleo). A push needs a new review; a later BLOCK at this head dismisses this approval.

[teamleaderleo]

Review (codex, router-review): SHIP at c857477

Reviewer: codex gpt-6-astra high, fast tier.

Leo-Ask-Trace: ask-a933b133a7

Follow-ups: 2. They land as checklist items in this PR's one follow-up tracking issue in this repo (Follow-ups: #N ..., label follow-up; add to an open one before filing, never one issue per finding), linking this receipt; the lane that opened the PR fixes them forward.

SHIP at c857477

Visual verdict: no images; Leo tries the build

• [P2] [follow-up] [category:correctness] [finding:F1] [outcome:pending] Guidance and skills are snapshotted at chat creation (cmux-tui/crates/acpmux/src/agent_guidance.rs:245-253), but Claude’s plugin is rebuilt from current settings at spawn (cmux-tui/crates/acpmux/src/agent_tools.rs:668-678). A queued chat can therefore receive hidden guidance while its plugin omits cmux-chat, or have a stale skill index versus the copied plugin, if settings or skills change before startup. Use one creation-time snapshot for both.

• [P2] [follow-up] [category:correctness] [finding:F2] [outcome:pending] Turning off agents.guidance.claude removes cmux-chat from the plugin, but tool_rows and context inventory still enumerate every SKILL_FILES entry whenever any plugin exists (cmux-tui/crates/acpmux/src/agent_tools.rs:838-840, cmux-tui/crates/acpmux/src/agent_tools/prompt_sources.rs:146-165). The disabled skill remains shown as available; filter these listings using the same switch.

Follow-ups:

• F1: Snapshot guidance/settings and plugin inputs consistently at chat creation.
• F2: Stop advertising cmux-chat when Claude guidance is disabled.

[cmux-bot]

cmux-bot approves c857477: an independent review passed this exact head (router-review receipt by teamleaderleo). A push needs a new review; a later BLOCK at this head dismisses this approval.