feat(dev): add explicit tmux multiplexer launch

.claude-plugin/skills/agent-cli-dev/SKILL.md

@@ -1,12 +1,16 @@
 ---
 name: agent-cli-dev
-description: Spawns AI coding agents in isolated git worktrees. Use when the user asks to spawn or launch an agent, delegate a task to a separate agent, work in a separate worktree, or parallelize development across features.
+description: Spawns AI coding agents in isolated git worktrees. Use when the user asks to spawn or launch an agent, delegate a task to a separate agent, or parallelize development across features. Only create a worktree without starting an agent if the user explicitly wants setup only.
 ---
 
 # Parallel Development with agent-cli dev
 
 This skill teaches you how to spawn parallel AI coding agents in isolated git worktrees using the `agent-cli dev` command.
 
+`agent-cli dev` supports two complementary patterns:
+- Separate worktrees for isolated implementation/review tasks
+- Multiple agents on the same worktree using `dev agent -m tmux`
+
 ## Installation
 
 If `agent-cli` is not available, install it first:
@@ -58,6 +62,16 @@ This creates:
 
 **Important**: Use `--prompt-file` for prompts longer than a single line. The `--prompt` option passes text through the shell, which can cause issues with special characters (exclamation marks, dollar signs, backticks, quotes) in ZSH and other shells. Using `--prompt-file` avoids all shell quoting issues.
 
+## Automation rule
+
+When an assistant is executing this workflow on the user's behalf, the spawn is not complete unless the agent receives a prompt at launch time.
+
+- Prefer `--prompt-file`; create the prompt file first, then launch the agent
+- Use `dev new ... --agent --prompt-file ...` for a new delegated task
+- Use `dev agent ... --prompt-file ...` for another agent in an existing worktree
+- Do not stop after `dev new ...` alone if the user's intent was to delegate work immediately
+- Do not run `dev new ... --agent` or `dev agent ... -m tmux` without `--prompt` or `--prompt-file` unless the user explicitly wants an interactive session that they will drive manually
+
 ## Writing effective prompts for spawned agents
 
 Spawned agents work in isolation, so prompts must be **self-contained**. Include:
@@ -76,7 +90,7 @@ For any prompt longer than a single sentence:
 
 Example workflow:
 ```bash
-# 1. Write prompt to file (Claude does this with the Write tool)
+# 1. Write prompt to file
 # 2. Spawn agent with the file
 agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md
 # 3. Optionally clean up
@@ -114,6 +128,54 @@ agent-cli dev run <branch-name> cat .claude/REPORT.md
 agent-cli dev editor <branch-name>
 ```
 
+## Same-branch multi-agent workflow
+
+Use this when several agents should inspect or validate the same code at once without separate worktrees.
+
+```bash
+# Create the worktree once. This step only prepares the shared workspace.
+agent-cli dev new review-auth --from HEAD
+
+# Then launch the actual agents with prompts.
+agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-security.md
+agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-performance.md
+agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-tests.md
+```
+
+Key rules for same-worktree launches:
+- Use `dev agent`, not `dev new`, after the worktree already exists
+- Use `-m tmux` for headless or scripted launching; it works even when not already inside tmux
+- Each launch joins the same deterministic repo-scoped tmux session, so related agents stay grouped together
+- Ask each agent to write to a unique report path such as `.claude/REPORT-security-<run-id>.md` or `.claude/REPORT-tests-<run-id>.md`
+- If you rerun the same prompt repeatedly, include a timestamp or other run id in the report filename so later runs do not overwrite earlier ones
+- Do not rely on `.claude/TASK.md` as per-agent state in shared worktrees; later launches overwrite it
+
+### Prompt guidance for shared worktrees
+
+When multiple agents share a worktree, explicitly assign both a focus area and a unique report file. If you rerun the same review prompt often, prefer a timestamped filename such as `.claude/REPORT-security-20260319-153045-123.md`.
+
+Prompt pattern:
+
+```text
+Review the auth module for security issues only.
+
+When complete, write findings to .claude/REPORT-security-20260319-153045-123.md including:
+- Summary
+- Issues found with file/line references
+- Suggested fixes
+```
+
+## Headless/scripted orchestration
+
+For non-interactive contexts (scripts, cron jobs, other assistants), combine `--prompt-file` with `-m tmux`:
+
+```bash
+agent-cli dev new validation-a --from HEAD --agent --with-agent codex -m tmux \
+  --prompt-file .claude/validation-a.md
+```
+
+This works without an attached terminal. `agent-cli` creates or reuses a detached tmux session and returns a pane handle plus attach command.
+
 ## Example: Multi-feature implementation
 
 If asked to implement auth, payments, and notifications:

.claude-plugin/skills/agent-cli-dev/examples.md

@@ -8,6 +8,8 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud
 > # Write prompt to file, then spawn
 > agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md
 > ```
+>
+> When an assistant is executing these commands, do not launch `dev new` or `dev agent` without `--prompt` or `--prompt-file` unless the user explicitly wants a manual interactive session.
 
 ## Prompt structure guidelines
 
@@ -19,6 +21,7 @@ Each prompt for a spawned agent should follow this structure:
 4. **Context with motivation** - Explain why patterns matter
 5. **Focused scope** - Keep solutions minimal, implement only what's requested
 6. **Structured report** - Write conclusions to `.claude/REPORT.md`
+7. **No interactive gap** - The launch command itself should include `--prompt` or `--prompt-file` so the agent starts working immediately
 
 ## Scenario 1: Code review of current branch
 
@@ -524,6 +527,96 @@ When complete, write to .claude/REPORT.md:
 </report>"
 ```
 
+## Scenario 6: Multi-reviewer on the same branch
+
+**User request**: "Get 3 agents to review this code" or "Run multiple reviewers on this branch"
+
+**Strategy**: Create one review worktree from the current branch, then launch several agents into that same worktree with different focus areas.
+
+```bash
+run_id="$(python -c 'import time; print(int(time.time() * 1000))')"
+
+# Create the shared review worktree once. This does not start an agent yet.
+agent-cli dev new review-auth --from HEAD
+
+# Launch three reviewers into the same worktree/session
+agent-cli dev agent review-auth -m tmux --prompt "Review the auth module for security issues only.
+
+<scope>
+Do not fix code. Review only.
+</scope>
+
+<report>
+Write findings to .claude/REPORT-security-$run_id.md:
+- Summary
+- Issues with file:line references
+- Suggested fixes
+</report>"
+
+agent-cli dev agent review-auth -m tmux --prompt "Review the auth module for performance issues only.
+
+<scope>
+Review only. Focus on query patterns, repeated work, and unnecessary allocations.
+</scope>
+
+<report>
+Write findings to .claude/REPORT-performance-$run_id.md:
+- Summary
+- Issues with file:line references
+- Suggested fixes
+</report>"
+
+agent-cli dev agent review-auth -m tmux --prompt "Review the auth module for test coverage gaps only.
+
+<scope>
+Review only. Identify missing or weak tests.
+</scope>
+
+<report>
+Write findings to .claude/REPORT-tests-$run_id.md:
+- Summary
+- Missing test cases
+- Suggested follow-up tests
+</report>"
+```
+
+**Important**:
+- Same-worktree launches should use unique report files, not `.claude/REPORT.md`
+- If you rerun the same prompt often, include a timestamp or run id in the filename so reports do not get replaced
+- `-m tmux` works even when the caller is not already inside tmux
+- All three agents land in the same deterministic tmux session for that repo
+- `.claude/TASK.md` is shared state and may be overwritten by later launches, so keep prompt files outside that convention
+
+## Scenario 7: Parallel test validation
+
+**User request**: "Run the test checklist across 8 sections in parallel"
+
+**Strategy**: Create one worktree per section, then launch each validation agent headlessly in tmux so the workflow works from scripts or non-terminal orchestrators.
+
+```bash
+for section in 1 2 3 4 5 6 7 8; do
+  agent-cli dev new "test-section-$section" --from HEAD --agent --with-agent codex -m tmux \
+    --prompt-file ".claude/test-section-$section.md"
+done
+```
+
+Monitor and collect results:
+
+```bash
+# Track the worktrees
+agent-cli dev status
+
+# Read each report after completion
+for section in 1 2 3 4 5 6 7 8; do
+  agent-cli dev run "test-section-$section" cat .claude/REPORT.md
+done
+```
+
+**When writing the per-section prompts**:
+- Assign one checklist section per agent
+- Require real test execution where possible
+- Require a structured `.claude/REPORT.md` with pass/fail status, evidence, and follow-up actions
+
 ## Reviewing results
 
 After agents complete their work:
@@ -569,3 +662,8 @@ Any items that need human review or clarification
 ```
 
 This consistent format makes it easy to review work from multiple agents.
+
+For shared-worktree runs, keep the same structure but use unique filenames such as:
+- `.claude/REPORT-security.md`
+- `.claude/REPORT-performance.md`
+- `.claude/REPORT-tests.md`

.claude/skills/agent-cli-dev/SKILL.md

@@ -1,12 +1,16 @@
 ---
 name: agent-cli-dev
-description: Spawns AI coding agents in isolated git worktrees. Use when the user asks to spawn or launch an agent, delegate a task to a separate agent, work in a separate worktree, or parallelize development across features.
+description: Spawns AI coding agents in isolated git worktrees. Use when the user asks to spawn or launch an agent, delegate a task to a separate agent, or parallelize development across features. Only create a worktree without starting an agent if the user explicitly wants setup only.
 ---
 
 # Parallel Development with agent-cli dev
 
 This skill teaches you how to spawn parallel AI coding agents in isolated git worktrees using the `agent-cli dev` command.
 
+`agent-cli dev` supports two complementary patterns:
+- Separate worktrees for isolated implementation/review tasks
+- Multiple agents on the same worktree using `dev agent -m tmux`
+
 ## Installation
 
 If `agent-cli` is not available, install it first:
@@ -58,6 +62,16 @@ This creates:
 
 **Important**: Use `--prompt-file` for prompts longer than a single line. The `--prompt` option passes text through the shell, which can cause issues with special characters (exclamation marks, dollar signs, backticks, quotes) in ZSH and other shells. Using `--prompt-file` avoids all shell quoting issues.
 
+## Automation rule
+
+When an assistant is executing this workflow on the user's behalf, the spawn is not complete unless the agent receives a prompt at launch time.
+
+- Prefer `--prompt-file`; create the prompt file first, then launch the agent
+- Use `dev new ... --agent --prompt-file ...` for a new delegated task
+- Use `dev agent ... --prompt-file ...` for another agent in an existing worktree
+- Do not stop after `dev new ...` alone if the user's intent was to delegate work immediately
+- Do not run `dev new ... --agent` or `dev agent ... -m tmux` without `--prompt` or `--prompt-file` unless the user explicitly wants an interactive session that they will drive manually
+
 ## Writing effective prompts for spawned agents
 
 Spawned agents work in isolation, so prompts must be **self-contained**. Include:
@@ -76,7 +90,7 @@ For any prompt longer than a single sentence:
 
 Example workflow:
 ```bash
-# 1. Write prompt to file (Claude does this with the Write tool)
+# 1. Write prompt to file
 # 2. Spawn agent with the file
 agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md
 # 3. Optionally clean up
@@ -114,6 +128,54 @@ agent-cli dev run <branch-name> cat .claude/REPORT.md
 agent-cli dev editor <branch-name>
 ```
 
+## Same-branch multi-agent workflow
+
+Use this when several agents should inspect or validate the same code at once without separate worktrees.
+
+```bash
+# Create the worktree once. This step only prepares the shared workspace.
+agent-cli dev new review-auth --from HEAD
+
+# Then launch the actual agents with prompts.
+agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-security.md
+agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-performance.md
+agent-cli dev agent review-auth -m tmux --prompt-file .claude/review-tests.md
+```
+
+Key rules for same-worktree launches:
+- Use `dev agent`, not `dev new`, after the worktree already exists
+- Use `-m tmux` for headless or scripted launching; it works even when not already inside tmux
+- Each launch joins the same deterministic repo-scoped tmux session, so related agents stay grouped together
+- Ask each agent to write to a unique report path such as `.claude/REPORT-security-<run-id>.md` or `.claude/REPORT-tests-<run-id>.md`
+- If you rerun the same prompt repeatedly, include a timestamp or other run id in the report filename so later runs do not overwrite earlier ones
+- Do not rely on `.claude/TASK.md` as per-agent state in shared worktrees; later launches overwrite it
+
+### Prompt guidance for shared worktrees
+
+When multiple agents share a worktree, explicitly assign both a focus area and a unique report file. If you rerun the same review prompt often, prefer a timestamped filename such as `.claude/REPORT-security-20260319-153045-123.md`.
+
+Prompt pattern:
+
+```text
+Review the auth module for security issues only.
+
+When complete, write findings to .claude/REPORT-security-20260319-153045-123.md including:
+- Summary
+- Issues found with file/line references
+- Suggested fixes
+```
+
+## Headless/scripted orchestration
+
+For non-interactive contexts (scripts, cron jobs, other assistants), combine `--prompt-file` with `-m tmux`:
+
+```bash
+agent-cli dev new validation-a --from HEAD --agent --with-agent codex -m tmux \
+  --prompt-file .claude/validation-a.md
+```
+
+This works without an attached terminal. `agent-cli` creates or reuses a detached tmux session and returns a pane handle plus attach command.
+
 ## Example: Multi-feature implementation
 
 If asked to implement auth, payments, and notifications: