From 142ae2348cf34de6f76c8881322a89d351561848 Mon Sep 17 00:00:00 2001
From: Danil Pismenny <dapi@users.noreply.github.com>
Date: Fri, 7 Aug 2026 19:14:54 +0500
Subject: [PATCH 1/2] Add start-issue cmux skill

---
 skills/start-issue-cmux/SKILL.md              |  80 ++++++++++++
 skills/start-issue-cmux/agents/openai.yaml    |   7 +
 .../references/cmux-layouts.md                |  23 ++++
 .../start-issue-cmux/references/lifecycle.md  |  30 +++++
 skills/start-issue-cmux/scripts/start-in-cmux | 121 ++++++++++++++++++
 5 files changed, 261 insertions(+)
 create mode 100644 skills/start-issue-cmux/SKILL.md
 create mode 100644 skills/start-issue-cmux/agents/openai.yaml
 create mode 100644 skills/start-issue-cmux/references/cmux-layouts.md
 create mode 100644 skills/start-issue-cmux/references/lifecycle.md
 create mode 100755 skills/start-issue-cmux/scripts/start-in-cmux

diff --git a/skills/start-issue-cmux/SKILL.md b/skills/start-issue-cmux/SKILL.md
new file mode 100644
index 0000000..b3c55ee
--- /dev/null
+++ b/skills/start-issue-cmux/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: start-issue-cmux
+description: Launch and monitor start-issue work in a dedicated cmux workspace. Use when a user wants a GitHub issue started through start-issue in a separate cmux tab/workspace, resumed without duplicate worktrees or agents, or monitored through cmux status and screen output.
+---
+
+# Start Issue in cmux
+
+Use this skill as a thin orchestration layer between `start-issue` and cmux. `start-issue` remains the source of truth for GitHub issue resolution, branch naming, worktree creation/reuse, init hooks, prompt rendering, and agent launch. cmux provides the terminal workspace and optional monitoring surfaces.
+
+## Preconditions
+
+- The user explicitly requested cmux, a separate tab/workspace, or resume/monitoring of a start-issue run.
+- The target repository and issue URL/number are known.
+- `cmux`, `start-issue`, and `git` are available.
+- Use the repository's normal environment loader. If the repository has `.envrc`, launch `start-issue` through `direnv exec .`.
+
+Do not create a worktree manually. Do not invoke an agent directly when the request is to start an issue: delegate that lifecycle to `start-issue`.
+
+## Quick start
+
+From the target repository:
+
+```bash
+<installed-skill-dir>/scripts/start-in-cmux \
+  https://github.com/OWNER/REPO/issues/123 \
+  --agent codex
+```
+
+The installed skill directory depends on the installer (commonly `~/.codex/skills/start-issue-cmux` or `~/.agents/skills/start-issue-cmux`). When working from a checkout of this repository, the equivalent path is `skills/start-issue-cmux/scripts/start-in-cmux`.
+
+The launcher creates a workspace named `start-issue #123`, keeps the current workspace focused by default, and runs:
+
+```bash
+direnv exec . start-issue <issue> --agent codex
+```
+
+If `.envrc` is absent, it runs `start-issue` directly. Pass `--focus` only when the user explicitly wants cmux to switch focus.
+
+## Workflow
+
+1. Resolve the target repository and issue. Prefer the full GitHub issue URL when available.
+2. Inspect the current caller context with `cmux identify --json` if already inside cmux. Do not infer a target workspace from global focus.
+3. Run `scripts/start-in-cmux` with the explicit issue and agent. Let `start-issue` resolve or reuse the worktree.
+4. Record the returned cmux workspace reference and the worktree path printed by `start-issue`.
+5. For status checks, read the named workspace with `cmux read-screen --workspace <ref> --scrollback --lines <n>` and inspect `cmux sidebar-state --workspace <ref> --json` when available.
+6. Treat the agent's own terminal output and `start-issue` state as authoritative. Do not send follow-up input unless the user names the workspace and asks for it.
+7. On resume, locate the existing workspace/worktree first. Never create a second worktree or launch a second agent for the same issue without explicit user direction.
+
+## Status handling
+
+- Agent working: leave the workspace running; do not interrupt or send speculative input.
+- `STATUS: WAIT`: report the expected external event and keep the workspace available for resume.
+- `STATUS: HUMAN_GATE`: report the exact decision or approval required; do not send an answer on the user's behalf.
+- `STATUS: DONE`: report the worktree, branch, commit/PR evidence shown by the agent, and remaining review steps.
+
+Use cmux notifications or sidebar status only as attention cues. They do not replace the issue, agent, CI, or repository state.
+
+## Layout guidance
+
+Start with one terminal surface. Add panes only when useful and only in the named workspace:
+
+- terminal: the `start-issue` agent;
+- optional terminal: logs or a test watcher;
+- optional browser: local/stage verification;
+- optional Markdown viewer: plan or handoff notes.
+
+Prefer additive pane creation with `--focus false`. Do not close or modify unrelated workspaces. For browser automation, load the official `cmux-browser` skill; for settings/layout customization, load `cmux-customization`.
+
+## Safety boundaries
+
+- No merge, release, deploy, production mutation, or external message is implied by this skill.
+- Do not bypass `start-issue` with manual `git worktree add`, direct agent launch, or a second orchestration runtime.
+- Do not put tokens, credentials, or rendered secret environment values in workspace descriptions, cmux actions, prompts, logs, or issue comments.
+- Do not focus, send input to, move, or close another workspace unless the user explicitly identifies it.
+- If cmux is unavailable, report the diagnostic blocker and offer the normal `start-issue` command; do not silently fall back when the user specifically requested a separate cmux workspace.
+
+## References
+
+- Read [lifecycle.md](references/lifecycle.md) for start/resume/status/finish behavior.
+- Read [cmux-layouts.md](references/cmux-layouts.md) when the user requests helper panes, browser surfaces, or a repeatable project layout.
diff --git a/skills/start-issue-cmux/agents/openai.yaml b/skills/start-issue-cmux/agents/openai.yaml
new file mode 100644
index 0000000..6489872
--- /dev/null
+++ b/skills/start-issue-cmux/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+  display_name: "Start Issue in cmux"
+  short_description: "Launch and monitor issue work in cmux"
+  default_prompt: "Use $start-issue-cmux to launch this GitHub issue in a dedicated cmux workspace and monitor its agent lifecycle."
+
+policy:
+  allow_implicit_invocation: true
diff --git a/skills/start-issue-cmux/references/cmux-layouts.md b/skills/start-issue-cmux/references/cmux-layouts.md
new file mode 100644
index 0000000..2c185e6
--- /dev/null
+++ b/skills/start-issue-cmux/references/cmux-layouts.md
@@ -0,0 +1,23 @@
+# cmux layout patterns
+
+Start with a single terminal surface. Add only the surfaces needed by the issue.
+
+## Test/log helper pane
+
+```bash
+cmux new-pane --workspace workspace:16 --type terminal --direction right --focus false
+```
+
+Send commands only to the returned surface, and only after the user has named the target workspace or requested this layout.
+
+## Browser verification
+
+Use the official `cmux-browser` skill for browser actions. Keep the browser in the same named workspace as the agent and do not copy authentication data into prompts or workspace metadata.
+
+## Markdown handoff
+
+Use the official `cmux-markdown` skill to show an existing plan or handoff file. Do not create a second live state journal in cmux; repository state, issue state, and agent state remain canonical.
+
+## Project customization
+
+Use `cmux-customization` for reusable `.cmux/` project layouts, actions, buttons, and Dock controls. Keep project-specific commands in the project config; keep this skill generic.
diff --git a/skills/start-issue-cmux/references/lifecycle.md b/skills/start-issue-cmux/references/lifecycle.md
new file mode 100644
index 0000000..2539df9
--- /dev/null
+++ b/skills/start-issue-cmux/references/lifecycle.md
@@ -0,0 +1,30 @@
+# start-issue + cmux lifecycle
+
+## Start
+
+1. Confirm the issue URL/number, repository, agent, and whether focus is wanted.
+2. From the repository root, run `scripts/start-in-cmux <issue> --agent <agent>`.
+3. Capture the workspace reference printed by cmux and the worktree/branch printed by `start-issue`.
+4. `start-issue` owns all GitHub, branch, worktree, init-hook, prompt, and agent operations.
+
+## Resume
+
+1. List workspaces and identify the one named for the issue.
+2. Read its screen and inspect the expected worktree path.
+3. Confirm the worktree branch matches the issue branch before interacting.
+4. If an agent session is resumable, use the supported start-issue/agent resume path. Otherwise report the blocker; do not launch a duplicate agent automatically.
+
+## Monitor
+
+Use explicit workspace refs:
+
+```bash
+cmux read-screen --workspace workspace:16 --scrollback --lines 120
+cmux sidebar-state --workspace workspace:16 --json
+```
+
+A terminal screen is evidence of what the agent displayed, not proof that GitHub or CI state has changed. Verify commits, PRs, and checks through their canonical tools.
+
+## Finish
+
+When the agent reports `STATUS: DONE`, summarize the exact artifacts it reported. Keep the workspace open unless the user asks to close it. A completed agent run does not authorize merge, release, deploy, or production actions.
diff --git a/skills/start-issue-cmux/scripts/start-in-cmux b/skills/start-issue-cmux/scripts/start-in-cmux
new file mode 100755
index 0000000..449a9a3
--- /dev/null
+++ b/skills/start-issue-cmux/scripts/start-in-cmux
@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: start-in-cmux ISSUE [--agent AGENT] [--repo OWNER/REPO] [--cwd DIR] [--name NAME] [--focus]
+
+Create a dedicated cmux workspace and run start-issue inside it.
+EOF
+}
+
+if [[ $# -lt 1 || "$1" == "-h" || "$1" == "--help" ]]; then
+  usage >&2
+  [[ $# -ge 1 ]] && [[ "$1" == "-h" || "$1" == "--help" ]] && exit 0
+  exit 2
+fi
+
+issue="$1"
+shift
+agent="${START_ISSUE_AGENT:-codex}"
+repo=""
+cwd="$(pwd -P)"
+name=""
+focus="false"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --agent)
+      [[ $# -ge 2 ]] || { echo "--agent requires a value" >&2; exit 2; }
+      agent="$2"
+      shift 2
+      ;;
+    --repo)
+      [[ $# -ge 2 ]] || { echo "--repo requires a value" >&2; exit 2; }
+      repo="$2"
+      shift 2
+      ;;
+    --cwd)
+      [[ $# -ge 2 ]] || { echo "--cwd requires a value" >&2; exit 2; }
+      cwd="$2"
+      shift 2
+      ;;
+    --name)
+      [[ $# -ge 2 ]] || { echo "--name requires a value" >&2; exit 2; }
+      name="$2"
+      shift 2
+      ;;
+    --focus)
+      focus="true"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+for required_command in cmux git start-issue; do
+  command -v "$required_command" >/dev/null 2>&1 || {
+    echo "Required command not found: $required_command" >&2
+    exit 1
+  }
+done
+
+[[ -d "$cwd" ]] || { echo "Directory does not exist: $cwd" >&2; exit 1; }
+cwd="$(cd "$cwd" && pwd -P)"
+git -C "$cwd" rev-parse --show-toplevel >/dev/null 2>&1 || {
+  echo "--cwd must point to a Git repository" >&2
+  exit 1
+}
+
+issue_number="${issue##*/}"
+issue_number="${issue_number%/}"
+issue_number="${issue_number#\#}"
+if [[ ! "$issue_number" =~ ^[0-9]+$ ]]; then
+  issue_number="issue"
+fi
+
+if [[ -z "$name" ]]; then
+  repo_name="$(basename "$(git -C "$cwd" rev-parse --show-toplevel)")"
+  name="$repo_name #$issue_number"
+fi
+
+start_command=(start-issue "$issue" --agent "$agent")
+if [[ -n "$repo" ]]; then
+  start_command+=(--repo "$repo")
+fi
+
+if [[ -f "$cwd/.envrc" ]] && command -v direnv >/dev/null 2>&1; then
+  launch_command=(direnv exec . "${start_command[@]}")
+else
+  launch_command=("${start_command[@]}")
+fi
+
+quote_for_shell() {
+  printf '%q ' "$1"
+}
+
+command_text=""
+for argument in "${launch_command[@]}"; do
+  command_text+="$(quote_for_shell "$argument")"
+done
+
+focus_args=(--focus false)
+if [[ "$focus" == "true" ]]; then
+  focus_args=(--focus true)
+fi
+
+printf 'Creating cmux workspace %q in %s\n' "$name" "$cwd"
+cmux new-workspace \
+  --name "$name" \
+  --description "start-issue: $issue" \
+  --cwd "$cwd" \
+  --command "$command_text" \
+  "${focus_args[@]}"

From d65c3d1bcc3e0e75f7581367e3136e3bca31170c Mon Sep 17 00:00:00 2001
From: Danil Pismenny <dapi@users.noreply.github.com>
Date: Fri, 7 Aug 2026 19:20:29 +0500
Subject: [PATCH 2/2] Document cmux skill usage examples

---
 skills/start-issue-cmux/SKILL.md | 56 ++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/skills/start-issue-cmux/SKILL.md b/skills/start-issue-cmux/SKILL.md
index b3c55ee..332e607 100644
--- a/skills/start-issue-cmux/SKILL.md
+++ b/skills/start-issue-cmux/SKILL.md
@@ -36,6 +36,62 @@ direnv exec . start-issue <issue> --agent codex
 
 If `.envrc` is absent, it runs `start-issue` directly. Pass `--focus` only when the user explicitly wants cmux to switch focus.
 
+## Example user requests
+
+These are representative prompts that should trigger this skill. The clearest form names the issue, asks for cmux/start-issue, and names the agent when relevant.
+
+### Start an issue
+
+```text
+Запусти GitHub issue #5001 в отдельной вкладке cmux через start-issue, агент Codex.
+```
+
+```text
+Открой issue https://github.com/BrandyMint/merchantly/issues/5001
+в отдельном cmux workspace и начни реализацию через start-issue.
+```
+
+```text
+Из репозитория /Users/danil/code/brandymint/merchantly
+запусти issue #5001 в отдельной cmux-вкладке через start-issue.
+```
+
+```text
+Используй $start-issue-cmux и запусти issue #5001 в репозитории merchantly через Codex.
+```
+
+### Resume and monitor
+
+```text
+Возобнови работу над issue #5001 в существующем cmux workspace.
+Не создавай новый worktree и второго агента.
+```
+
+```text
+Проверь статус агента, который работает над issue #5001 через start-issue.
+```
+
+```text
+Прочитай последние 100 строк из вкладки cmux для merchantly #5001
+и скажи, ждёт ли агент человека.
+```
+
+### Add helper surfaces
+
+```text
+Для issue #5001 добавь справа в том же cmux workspace отдельную панель для логов.
+```
+
+```text
+Запусти issue #5001 в cmux и добавь browser surface для проверки localhost.
+```
+
+```text
+Покажи implementation plan issue #5001 в Markdown-панели рядом с терминалом агента.
+```
+
+Plain requests such as `почини issue #5001` do not necessarily request cmux integration. In that case, use the normal `start-issue` workflow unless the user explicitly names cmux or invokes `$start-issue-cmux`.
+
 ## Workflow
 
 1. Resolve the target repository and issue. Prefer the full GitHub issue URL when available.